luke
/
prjxray
mirror of https://github.com/openXC7/prjxray.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1036 from SymbiFlow/docs 

Update the UPDATING THE DOCS doc
This commit is contained in:
Tim Ansell 2019-08-28 09:34:01 +02:00 committed by GitHub
parent 76eb5d45d9 d619394748
commit ca2afec39c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
UPDATING-THE-DOCS.md
View File

@ -1,8 +1,9 @@
# Guide to updating the Project X-Ray docs # Guide to updating the Project X-Ray docs
We welcome updates to the Project X-Ray docs. The docs are published on [Read We welcome updates to the Project X-Ray docs. The docs are published on [Read
the Docs](http://prjxray.readthedocs.io) and the source is on the Docs](http://prjxray.readthedocs.io) and the source is on the [docs branch on GitHub](https://github.com/SymbiFlow/prjxray/tree/docs/docs).
[GitHub](https://github.com/SymbiFlow/prjxray/tree/master/docs).
The reason for using the `docs` branch is to avoid running the full CI test suite which triggers when merging anything to `master`. Ultimately of course the `docs` branch needs to be synchronized with `master`, but this can be done in bulk.
Updating the docs is a three-step process: Make your updates, test your updates, Updating the docs is a three-step process: Make your updates, test your updates,
send a pull request. send a pull request.
@ -24,7 +25,7 @@ effects of your changes on the page you've updated and on the docs as a whole.
There are a few places on the web where you can view ReStructured Text rendered There are a few places on the web where you can view ReStructured Text rendered
as HTML. For example: as HTML. For example:
[https://livesphinx.herokuapp.com/](https://livesphinx.herokuapp.com/) [https://livesphinx.herokuapp.com/](https://livesphinx.herokuapp.com/)
## Perform basic tests: make html and linkcheck ## Perform basic tests: make html and linkcheck
@ -32,10 +33,10 @@ If your changes are quite simple, you can perform a few basic checks before
sending a pull request. At minimum: sending a pull request. At minimum:
- Check that `make html` generates output without errors - Check that `make html` generates output without errors
- Check that `make linkcheck` reports no warnings. - Check that `make linkcheck` reports no warnings.
- When editing, `make livehtml` is helpful. - When editing, `make livehtml` is helpful.
To make these checks work, you need to install Sphinx. We recommend `pipenv`. To make these checks work, you need to install Sphinx. We recommend `pipenv`.
Follow the steps below to install `pipenv` via `pip`, run `pipenv install` in Follow the steps below to install `pipenv` via `pip`, run `pipenv install` in
the `docs` directory, then run `pipenv shell` to enter an environment where the `docs` directory, then run `pipenv shell` to enter an environment where
@ -52,12 +53,12 @@ Steps in detail, on Linux:
guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv): guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv):
pip install pipenv pip install pipenv
1. Add pipenv to your path, as recommended in the 1. Add pipenv to your path, as recommended in the
[pipenv installation [pipenv installation
guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv). On guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv). On
Linux, add this in your `~/.profile` file: Linux, add this in your `~/.profile` file:
export PATH=$PATH:~/.local/bin source ~/.profile export PATH=$PATH:~/.local/bin source ~/.profile
Note: On OS X the path is different: `~/Library/Python/2.7/bin` Note: On OS X the path is different: `~/Library/Python/2.7/bin`
@ -65,7 +66,7 @@ Steps in detail, on Linux:
1. Go to the docs directory in the Project X-Ray repo: 1. Go to the docs directory in the Project X-Ray repo:
cd ~/github-repos/prjxray/docs cd ~/github-repos/prjxray/docs
1. Run pipenv to install the Sphinx environment: 1. Run pipenv to install the Sphinx environment:
pipenv install pipenv install
@ -110,7 +111,7 @@ Follow these steps to create your own staging doc site on Read the Docs (RtD):
Reason for protecting your doc site: If you leave your doc site public, it Reason for protecting your doc site: If you leave your doc site public, it
will appear in web searches. That may be confusing for readers who are will appear in web searches. That may be confusing for readers who are
looking for the canonical Project X-Ray docs. looking for the canonical Project X-Ray docs.
1. Set RtD to build from your branch, rather than from master. This ensures 1. Set RtD to build from your branch, rather than from `docs`. This ensures
that the content you see on your doc site reflect your latest updates: that the content you see on your doc site reflect your latest updates:
- On [your RtD dashboard](https://readthedocs.org/dashboard/), - On [your RtD dashboard](https://readthedocs.org/dashboard/),
open **your project**, then go to **Admin > Advanced Settings.** open **your project**, then go to **Admin > Advanced Settings.**