From 33371bcfd2ea7ec777a68a3d96a3a7ccabfab35a Mon Sep 17 00:00:00 2001 From: Jim Garrison Date: Wed, 26 Jul 2023 21:20:49 -0400 Subject: [PATCH] Improve the instructions regarding pandoc (#336) I've also tried to make the developer documentation easier to discover --- docs/index.rst | 5 +++++ test/README.md | 8 ++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 135741bb2..64cc7c0c1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,6 +27,11 @@ If you use the Circuit Knitting Toolbox in your research, please cite it accordi .. literalinclude:: ../CITATION.bib :language: bibtex +Developer guide +--------------- + +The developer guide is located at `CONTRIBUTING.md `__ in the root of this project's repository. + Contents -------- diff --git a/test/README.md b/test/README.md index fae561e03..1d6f4d028 100644 --- a/test/README.md +++ b/test/README.md @@ -61,14 +61,18 @@ $ tox -e coverage ## Documentation environment -The `docs` environment builds the [Sphinx] documentation locally. If the build succeeds, it can be viewed by navigating to `docs/_build/html/index.html` in a web browser. +The `docs` environment builds the [Sphinx] documentation locally. -To run: +For the documentation build to succeed, [pandoc](https://pandoc.org/) must be installed. Pandoc is not available via pip, so must be installed through some other means. Linux users are encouraged to install it through their package manager (e.g., `sudo apt-get install -y pandoc`), while macOS users are encouraged to install it via [Homebrew](https://brew.sh/) (`brew install pandoc`). Full instructions are available on [pandoc's installation page](https://pandoc.org/installing.html). + +To run this environment: ```sh $ tox -e docs ``` +If the build succeeds, it can be viewed by navigating to `docs/_build/html/index.html` in a web browser. Specifically, run `pwd` in the same terminal in which you built the docs, then copy that location and paste it in your web browser. You should see a directory listing there. If not, prepend `file://` to the path and try again. Once you see the directory listing, click on `docs`, then `_build`, then `html`, and then finally `index.html` to view the documentation. + [tox]: https://github.com/tox-dev/tox [`tox.ini`]: ../tox.ini [mypy]: https://mypy.readthedocs.io/en/stable/