From 59056d2d0901a1a4e47b36f98c45f33bed5c6fc2 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 30 Jun 2022 13:03:30 +0400 Subject: [PATCH 1/2] Switch README to Markdown --- CHANGELOG.md | 14 +++++----- CONTRIBUTING.md | 2 +- MANIFEST.in | 2 +- README.rst => README.md | 45 +++++++++++++------------------ docker/Dockerfiles/Dockerfile-dev | 2 +- setup.py | 5 ++-- 6 files changed, 31 insertions(+), 39 deletions(-) rename README.rst => README.md (80%) diff --git a/CHANGELOG.md b/CHANGELOG.md index aed0b3063..49c33f9a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1253,10 +1253,10 @@ ourselves. Major changes: -* Migrated the metrics data store from file-based to a dedicated Elasticsearch instance. Graphical reports can be created with - Kibana (optional but recommended). It is necessary to setup an Elasticsearch cluster to store metrics data (a single node - is sufficient). The cluster will be configured automatically by Rally. For details please see the [README](README.rst). - - Related issues: #8, #21, #46, - -[All changes](https://github.com/elastic/rally/issues?q=milestone0X0P+00.0.3+is0X0P+0closed) \ No newline at end of file +* Migrated the metrics data store from file-based to a dedicated Elasticsearch instance. Graphical reports can be created with + Kibana (optional but recommended). It is necessary to setup an Elasticsearch cluster to store metrics data (a single node + is sufficient). The cluster will be configured automatically by Rally. For details please see the documentation. + + Related issues: #8, #21, #46, + +[All changes](https://github.com/elastic/rally/issues?q=milestone0X0P+00.0.3+is0X0P+0closed) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7f9469e2..2586551a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,7 +83,7 @@ Note: Contributors belonging to the "Elastic" organization on Github can merge P **Repository:** [https://github.com/elastic/rally](https://github.com/elastic/rally) -Please follow the guidelines in the [README](README.rst) on the required software and the setup for development. +Please follow the guidelines in the [README](README.md) on the required software and the setup for development. ## License Headers diff --git a/MANIFEST.in b/MANIFEST.in index da4a0f38f..fe21ee43e 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -2,7 +2,7 @@ include CHANGELOG.md include CONTRIBUTING.md include LICENSE include MANIFEST.in -include README.rst +include README.md include setup.py include esrally/min-es-version.txt recursive-include docs * diff --git a/README.rst b/README.md similarity index 80% rename from README.rst rename to README.md index 8e1c84767..74b78d8e5 100644 --- a/README.rst +++ b/README.md @@ -1,10 +1,8 @@ -Rally -===== +# Rally Rally is the macrobenchmarking framework for Elasticsearch -What is Rally? --------------- +## What is Rally? You want to benchmark Elasticsearch? Then Rally is for you. It can help you with the following tasks: @@ -16,31 +14,28 @@ You want to benchmark Elasticsearch? Then Rally is for you. It can help you with We have also put considerable effort in Rally to ensure that benchmarking data are reproducible. -Quick Start ------------ +## Quick Start -Rally is developed for Unix and is actively tested on Linux and macOS. Rally supports `benchmarking Elasticsearch clusters running on Windows `_ but Rally itself needs to be installed on machines running Unix. +Rally is developed for Unix and is actively tested on Linux and macOS. Rally supports [benchmarking Elasticsearch clusters running on Windows](http://esrally.readthedocs.io/en/stable/recipes.html#benchmarking-an-existing-cluster) but Rally itself needs to be installed on machines running Unix. -Installing Rally -~~~~~~~~~~~~~~~~ +### Installing Rally **Note**: If you actively develop on Elasticsearch, we recommend that you `install Rally in development mode `_ instead as Elasticsearch is fast moving and Rally always adapts accordingly to the latest main version. -Install Python 3.8+ including ``pip3``, git 1.9+ and an `appropriate JDK to run Elasticsearch `_ Be sure that ``JAVA_HOME`` points to that JDK. Then run the following command, optionally prefixed by ``sudo`` if necessary:: +Install Python 3.8+ including `pip3`, git 1.9+ and an [appropriate JDK to run Elasticsearch](https://www.elastic.co/support/matrix#matrix_jvm>). Be sure that `JAVA_HOME` points to that JDK. Then run the following command, optionally prefixed by `sudo` if necessary: pip3 install esrally -If you have any trouble or need more detailed instructions, please look in the `detailed installation guide `_. +If you have any trouble or need more detailed instructions, please look in the [detailed installation guide](https://esrally.readthedocs.io/en/latest/install.html>). -Run your first race -------------------- +## Run your first race -Now we're ready to run our first race:: +Now we're ready to run our first race: esrally race --distribution-version=6.0.0 --track=geonames -This will download Elasticsearch 6.0.0 and run Rally's default track - the `geonames track `_ - against it. After the race, a summary report is written to the command line::: +This will download Elasticsearch 6.0.0 and run Rally's default track - the [geonames track](https://github.com/elastic/rally-tracks/tree/master/geonames>) - against it. After the race, a summary report is written to the command line: ------------------------------------------------------ _______ __ _____ @@ -101,21 +96,19 @@ This will download Elasticsearch 6.0.0 and run Rally's default track - the `geon ---------------------------------- -Getting help ------------- +## Getting help -* Quick help: ``esrally --help`` -* Look in `Rally's user guide `_ for more information -* Ask questions about Rally in the `Rally Discuss forum `_. -* File improvements or bug reports in our `Github repo `_. +* Quick help: `esrally --help` +* Look in [Rally's user guide](https://esrally.readthedocs.io/>) for more information +* Ask questions about Rally in the [Rally Discuss forum](https://discuss.elastic.co/tags/c/elastic-stack/elasticsearch/rally). +* File improvements or bug reports in our [Github repo](https://github.com/elastic/rally/issues>). -How to Contribute ------------------ +## How to Contribute -See all details in the `contributor guidelines `_. +See all details in the [contributor guidelines](https://github.com/elastic/rally/blob/master/CONTRIBUTING.md>). -License -------- + +## License This software is licensed under the Apache License, version 2 ("ALv2"), quoted below. diff --git a/docker/Dockerfiles/Dockerfile-dev b/docker/Dockerfiles/Dockerfile-dev index 055a4794c..ad10426b3 100644 --- a/docker/Dockerfiles/Dockerfile-dev +++ b/docker/Dockerfiles/Dockerfile-dev @@ -13,7 +13,7 @@ RUN apt-get -y update && \ RUN mkdir -p /rally/esrally COPY setup.py /rally/ COPY setup.cfg /rally/ -COPY README.rst /rally/ +COPY README.md /rally/ COPY MANIFEST.in /rally/ COPY esrally/ /rally/esrally/ diff --git a/setup.py b/setup.py index 3de965e56..7608d7752 100644 --- a/setup.py +++ b/setup.py @@ -33,8 +33,6 @@ def str_from_file(name): raw_version = str_from_file("esrally/_version.py") version = re.match(r'__version__ = "(.+)"', raw_version).group(1) -long_description = str_from_file("README.rst") - # tuples of (major, minor) of supported Python versions ordered from lowest to highest supported_python_versions = [(3, 8), (3, 9), (3, 10)] @@ -120,7 +118,8 @@ def str_from_file(name): maintainer_email="daniel.mitterdorfer@gmail.com", version=version, description="Macrobenchmarking framework for Elasticsearch", - long_description=long_description, + long_description=str_from_file("README.md"), + long_description_content_type="text/markdown", url="https://github.com/elastic/rally", license="Apache License, Version 2.0", packages=find_packages(where=".", exclude=("tests*", "benchmarks*", "it*")), From b8ddf3707c3380c29dc68683497b98ddebb9fe39 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Wed, 29 Jun 2022 11:59:30 +0400 Subject: [PATCH 2/2] Try Furo theme with new logo --- README.md | 4 +++- docs/conf.py | 22 +++------------------- docs/rally-logo.svg | 1 + setup.py | 2 +- 4 files changed, 8 insertions(+), 21 deletions(-) create mode 100644 docs/rally-logo.svg diff --git a/README.md b/README.md index 74b78d8e5..7708eb049 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# Rally +

Rally logo

+ +

Rally

Rally is the macrobenchmarking framework for Elasticsearch diff --git a/docs/conf.py b/docs/conf.py index e3bcd5a69..c45fb7122 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -128,26 +128,10 @@ def read_min_es_version(): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# html_theme = 'alabaster' +html_theme = "furo" -on_rtd = os.environ.get("READTHEDOCS", None) == "True" - -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - - html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# html_logo = None +html_static_path = ["."] +html_logo = "rally-logo.svg" # The name of an image file (relative to this directory) to use as a favicon of # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 diff --git a/docs/rally-logo.svg b/docs/rally-logo.svg new file mode 100644 index 000000000..b7f081707 --- /dev/null +++ b/docs/rally-logo.svg @@ -0,0 +1 @@ + diff --git a/setup.py b/setup.py index 7608d7752..879e4ee26 100644 --- a/setup.py +++ b/setup.py @@ -96,7 +96,7 @@ def str_from_file(name): develop_require = [ "tox==3.14.0", "sphinx==4.2.0", - "sphinx_rtd_theme==1.0.0", + "furo==2022.06.21", "twine==1.15.0", "wheel==0.33.6", "github3.py==1.3.0",