We use Sphinx to render, and readthedocs.org to publish, Brave Browser documentation. You can view the latest documentation at https://brave-browser.readthedocs.io/en/latest/.
Contributing to Brave Browser documentation can be done by editing the
docs/source/*.rst files in the brave-browser repository
and then opening a PR.
- Install
sphinxusing these instructions. - You might want to create a Python virtualenv or use Pipenv first to sequester these Python modules from your installed system modules.
- Install
To create or edit reStructuredText files in the source directory, follow this guide. The reStructuredText primer documents the markup that is supported by Sphinx.
After editing your content, you will render and view the documentation locally.
This is done by running the make html command from the docs directory.
Example:
[mbacchi@host docs]$ make html Running Sphinx v1.7.6 loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] docs looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded. The HTML pages are in build/html.
Now you can view the pages by pointing a web browser at the file
brave-browser/docs/build/html/index.html.
After you have verified the documentation looks like you want, you can commit it and open a PR in GitHub.
We have a project for the brave-browser repository already setup on readthedocs.org. You can view the latest documentation at https://brave-browser.readthedocs.io/en/latest/.
By default, readthedocs will render any new changes to the documentation nightly. But readthedocs.org also allows setting up a webhook that will render new changes to the live site when any commit lands in the repository. We will setup this webhook when Sphinx and readthedocs.org has been accepted as the documentation tool of choice by the entire team.