From 89128c48b7a9e5bb8c65c77ef00da7fabb8c8364 Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Sun, 29 Dec 2024 15:24:56 -0700 Subject: [PATCH] docs: consolidate developer docs + update contributing page for v3 --- docs/conf.py | 2 + docs/{ => developers}/contributing.rst | 70 +++++++------------------- docs/developers/index.rst | 10 ++++ docs/{ => developers}/release.rst | 0 docs/{ => developers}/roadmap.rst | 0 docs/index.rst | 5 +- 6 files changed, 31 insertions(+), 56 deletions(-) rename docs/{ => developers}/contributing.rst (85%) create mode 100644 docs/developers/index.rst rename docs/{ => developers}/release.rst (100%) rename docs/{ => developers}/roadmap.rst (100%) diff --git a/docs/conf.py b/docs/conf.py index e66a8a856..f81ef2eb4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,6 +91,8 @@ "spec/v3": "https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html", "license": "https://github.com/zarr-developers/zarr-python/blob/main/LICENSE.txt", "tutorial": "user-guide", + "release": "developers/release.html", + "roadmap": "developers/roadmap.html", } # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/docs/contributing.rst b/docs/developers/contributing.rst similarity index 85% rename from docs/contributing.rst rename to docs/developers/contributing.rst index 0ead6c826..9f17f7a92 100644 --- a/docs/contributing.rst +++ b/docs/developers/contributing.rst @@ -33,7 +33,7 @@ a bug report: # etc. ``` -2. An explanation of why the current behaviour is wrong/not desired, and what you +2. An explanation of why the current behavior is wrong/not desired, and what you expect instead. 3. Information about the version of Zarr, along with versions of dependencies and the @@ -46,8 +46,7 @@ a bug report: interpreter can be obtained by running a Python interactive session, e.g.:: $ python - Python 3.6.1 (default, Mar 22 2017, 06:17:05) - [GCC 6.3.0 20170321] on linux + Python 3.12.7 | packaged by conda-forge | (main, Oct 4 2024, 15:57:01) [Clang 17.0.6 ] on darwin Enhancement proposals --------------------- @@ -82,21 +81,21 @@ the "Fork" button. Then clone your fork to your local machine:: Creating a development environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To work with the Zarr source code, it is recommended to set up a Python virtual -environment and install all Zarr dependencies using the same versions as are used by +To work with the Zarr source code, it is recommended to use `hatch +`_ to create a virtual environment and +install all Zarr dependencies using the same versions as are used by the core developers and continuous integration services. Assuming you have a Python 3 interpreter already installed, and you have cloned the Zarr source code and your current working directory is the root of the repository, you can do something like the following:: - $ mkdir -p ~/pyenv/zarr-dev - $ python -m venv ~/pyenv/zarr-dev - $ source ~/pyenv/zarr-dev/bin/activate - $ pip install -e .[test,docs] + $ pip install hatch + $ hatch env show # list all available environments -To verify that your development environment is working, you can run the unit tests:: +To verify that your development environment is working, you can run the unit tests +for one of the test environments, e.g.:: - $ python -m pytest -v tests + $ hatch env run --env test.py3.12-2.1-optional run Creating a branch ~~~~~~~~~~~~~~~~~ @@ -143,40 +142,11 @@ spec. The simplest way to run the unit tests is to activate your development environment (see `creating a development environment`_ above) and invoke:: - $ python -m pytest -v zarr - -Some tests require optional dependencies to be installed, otherwise -the tests will be skipped. To install all optional dependencies, run:: - - $ pip install pytest-doctestplus - -To also run the doctests within docstrings (requires optional -dependencies to be installed), run:: - - $ python -m pytest -v --doctest-plus zarr - -To run the doctests within the tutorial and storage spec (requires -optional dependencies to be installed), run:: - - $ python -m doctest -o NORMALIZE_WHITESPACE -o ELLIPSIS docs/tutorial.rst docs/spec/v2.rst - -Note that some tests also require storage services to be running -locally. To run the Azure Blob Service storage tests, run an Azure -storage emulator (e.g., azurite) and set the environment variable -``ZARR_TEST_ABS=1``. If you're using Docker to run azurite, start the service with:: - - docker run --rm -p 10000:10000 mcr.microsoft.com/azure-storage/azurite azurite-blob --loose --blobHost 0.0.0.0 - -To run the Mongo DB storage tests, run a Mongo -server locally and set the environment variable ``ZARR_TEST_MONGO=1``. -To run the Redis storage tests, run a Redis server locally on port -6379 and set the environment variable ``ZARR_TEST_REDIS=1``. + $ hatch env run --env test.py3.12-2.1-optional run All tests are automatically run via GitHub Actions for every pull request and must pass before code can be accepted. Test coverage is -also collected automatically via the Codecov service, and total -coverage over all builds must be 100% (although individual builds -may be lower due to Python 2/3 or other differences). +also collected automatically via the Codecov service. Code standards - using pre-commit ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -209,11 +179,11 @@ the ``--no-verify`` option with ``git commit``. Test coverage ~~~~~~~~~~~~~ -Zarr maintains 100% test coverage under the latest Python stable release (currently -Python 3.8). Both unit tests and docstring doctests are included when computing +Zarr strives to maintain 100% test coverage under the latest Python stable release +(currently Python 3.12). Both unit tests and docstring doctests are included when computing coverage. Running:: - $ python -m pytest -v --cov=zarr --cov-config=pyproject.toml zarr + $ hatch env run --env test.py3.12-2.1-optional run-coverage will automatically run the test suite with coverage and produce a coverage report. This should be 100% before code can be accepted into the main code base. @@ -229,11 +199,7 @@ Docstrings for user-facing classes and functions should follow the `numpydoc `_ standard, including sections for Parameters and Examples. All examples -should run and pass as doctests under Python 3.8. To run doctests, -activate your development environment, install optional requirements, -and run:: - - $ python -m pytest -v --doctest-plus tests +should run and pass as doctests under Python 3.10. Zarr uses Sphinx for documentation, hosted on readthedocs.org. Documentation is written in the RestructuredText markup language (.rst files) in the ``docs`` folder. @@ -245,9 +211,7 @@ notes (``docs/release.rst``). The documentation can be built locally by running:: - $ cd docs - $ make clean; make html - $ open _build/html/index.html + $ hatch --env docs run build The resulting built documentation will be available in the ``docs/_build/html`` folder. diff --git a/docs/developers/index.rst b/docs/developers/index.rst new file mode 100644 index 000000000..3feb0aff7 --- /dev/null +++ b/docs/developers/index.rst @@ -0,0 +1,10 @@ + +Developer's Guide +----------------- + +.. toctree:: + :maxdepth: 1 + + contributing + release + roadmap diff --git a/docs/release.rst b/docs/developers/release.rst similarity index 100% rename from docs/release.rst rename to docs/developers/release.rst diff --git a/docs/roadmap.rst b/docs/developers/roadmap.rst similarity index 100% rename from docs/roadmap.rst rename to docs/developers/roadmap.rst diff --git a/docs/index.rst b/docs/index.rst index 05e326ed6..cbb634044 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,9 +11,8 @@ Zarr-Python getting_started user-guide/index api/index - release - contributing - roadmap + developers/index + developers/release **Version**: |version|