From 991afb0ed377271099b0654ee05605b347a62f90 Mon Sep 17 00:00:00 2001 From: Michael Waskom Date: Mon, 17 Aug 2020 18:14:29 -0400 Subject: [PATCH] Make a few edits to the new doc README --- README.md | 9 ++++++--- doc/README.md | 12 ++++++------ 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index cb4118872f..56edd9bcb0 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,8 @@ Online documentation is available at [seaborn.pydata.org](https://seaborn.pydata The docs include a [tutorial](https://seaborn.pydata.org/tutorial.html), [example gallery](https://seaborn.pydata.org/examples/index.html), [API reference](https://seaborn.pydata.org/api.html), and other useful information. +To build the documentation locally, please refer to [`doc/README.md`](doc/README.md). + Dependencies ------------ @@ -73,11 +75,12 @@ Testing Testing seaborn requires installing additional packages listed in `ci/utils.txt`. -To test the code, run `make test` in the source directory. This will exercise both the unit tests and docstring examples (using [pytest](https://docs.pytest.org/)). +To test the code, run `make test` in the source directory. This will exercise both the unit tests and docstring examples (using [pytest](https://docs.pytest.org/)) and generate a coverate report. + +The doctests require a network connection (unless all example datasets are cached), but the unit tests can be run offline with `make unittests`. -The doctests require a network connection (unless all example datasets are cached), but the unit tests can be run offline with `make unittests`. Run `make coverage` to generate a test coverage report and `make lint` to check code style consistency. -To build seaborn's documentation, please refer to [how to build the docs?](doc/README.md). +Code style is enforced with `flake8` using the settings in the [`setup.cfg`](./setup.cfg) file. Run `make lint` to check. Development ----------- diff --git a/doc/README.md b/doc/README.md index 1b45b8b31e..08ed1b11cd 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,10 +1,10 @@ -How to build the docs? -====================== +Building the seaborn docs +========================= -Building the docs requires installing the dependencies listed in `requirements.txt`. +Building the docs requires additional dependencies listed in [`./requirements.txt`](./requirements.txt). -The building process involves conversion of Jupyter notebooks to `rst` files. To facilitate this you need to set `NB_KERNEL` environment variable to the desired python kernel (e.g. `export NB_KERNEL="python3"`). To get a list of python kernels available, run `jupyter kernelspec list`. +The build process involves conversion of Jupyter notebooks to `rst` files. To facilitate this, you may need to set `NB_KERNEL` environment variable to the name of a kernel on your machine (e.g. `export NB_KERNEL="python3"`). To get a list of available Python kernels, run `jupyter kernelspec list`. -After you're set, from the `doc` directory run `make notebooks html` to convert all notebooks, build all gallery examples and the documentation iteslf. The designated output folder is `_build/html`. +After you're set up, run `make notebooks html` from the `doc` directory to convert all notebooks, generate all gallery examples, and build the documentation itself. The site will live in `_build/html`. -Run `make clean` to delete a built documentation. \ No newline at end of file +Run `make clean` to delete the built site and all intermediate files. Run `make -C docstrings clean` or `make -C tutorial clean` to remove intermediate files for the API or tutorial components.