From 6dc15342dff1ce72d09b53c2719b7c54bb79c6c4 Mon Sep 17 00:00:00 2001 From: Sarah Maddox Date: Mon, 7 May 2018 10:49:46 +1000 Subject: [PATCH 1/5] First commit of docs guide. Signed-off-by: Sarah Maddox --- README.md | 5 +++++ UPDATING-THE-DOCS.md | 1 + 2 files changed, 6 insertions(+) create mode 100644 UPDATING-THE-DOCS.md diff --git a/README.md b/README.md index b1e10bfa..b6edc9a2 100644 --- a/README.md +++ b/README.md @@ -234,3 +234,8 @@ following command to add signoffs to all commits between you and the upstream master: git rebase --signoff upstream/master + +### Contributing to the docs + +In addition to the above contribution guidelines, see the guide to +[updating the Project X-Ray docs](UPDATING-THE-DOCS.md). diff --git a/UPDATING-THE-DOCS.md b/UPDATING-THE-DOCS.md new file mode 100644 index 00000000..3ba5b13c --- /dev/null +++ b/UPDATING-THE-DOCS.md @@ -0,0 +1 @@ +Coming soon. From 132253fda43a88c80cfe2fb5ebc6ee81b5d89dcc Mon Sep 17 00:00:00 2001 From: Sarah Maddox Date: Mon, 7 May 2018 11:11:21 +1000 Subject: [PATCH 2/5] Links the term 'column' to the glossary entry. Signed-off-by: Sarah Maddox --- docs/architecture/configuration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/architecture/configuration.rst b/docs/architecture/configuration.rst index e75174f5..1e7da1a1 100644 --- a/docs/architecture/configuration.rst +++ b/docs/architecture/configuration.rst @@ -35,7 +35,8 @@ memories it contains. These busses are identified by a 3-bit integer: | 010 | CFG_CLB | ??? | +---------+-------------------+---------------------+ -Within each bus, the connected tiles are organized into columns. A column roughly +Within each bus, the connected tiles are organized into +:term:`columns `. A column roughly corresponds to a physical vertical line of tiles perpendicular to and centered over the horizontal clock row. Each column contains varying amounts of configuration data depending on the types of tiles attached to that column. Regardless of the amount, From a61361b1f7a80e755b9dd4bb9dd465554dd9bda1 Mon Sep 17 00:00:00 2001 From: Sarah Maddox Date: Mon, 7 May 2018 11:55:05 +1000 Subject: [PATCH 3/5] Added content to the guide to updating the docs. Signed-off-by: Sarah Maddox --- UPDATING-THE-DOCS.md | 132 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 1 deletion(-) diff --git a/UPDATING-THE-DOCS.md b/UPDATING-THE-DOCS.md index 3ba5b13c..40f9537f 100644 --- a/UPDATING-THE-DOCS.md +++ b/UPDATING-THE-DOCS.md @@ -1 +1,131 @@ -Coming soon. +# Guide to updating the Project X-Ray docs + +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 +[GitHub](https://github.com/SymbiFlow/prjxray/tree/master/docs). + +Updating the docs is a three-step process: Make your updates, test your updates, +send a pull request. + +# 1. Make your updates + +The standard Project X-Ray [contribution guidelines](CONTRIBUTING.md) apply to +doc updates too. + +Follow your usual process for updating content on GitHub. See GitHub's guide to +[working with forks](https://help.github.com/articles/working-with-forks/). + +# 2. Test your updates + +Before sending a pull request with your doc updates, you need to check the +effects of your changes on the page you've updated and on the docs as a whole. + +## Check your markup + +There are a few places on the web where you can view ReStructured Text rendered +as HTML. For example: +[https://livesphinx.herokuapp.com/](https://livesphinx.herokuapp.com/) + +## Perform basic tests: make html and linkcheck + +If your changes are quite simple, you can perform a few basic checks before +sending a pull request. At minimum: + +- Check that `make html` generates output without errors +- Check that `make linkcheck` reports no warnings. +- When editing, `make livehtml` is helpful. + +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 +the `docs` directory, then run `pipenv shell` to enter an environment where +Sphinx and all the necessary plugins are installed: + +Steps in detail, on Linux: + +- Install pip: + + sudo apt install python-pip + +- Install pipenv - see the + [pipenv installation + guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv): + + pip install pipenv + +- Add pipenv to your path, as recommended in the + [pipenv installation + guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv): + + - On Linux, add this in your ~/.profile file: + + export PATH=$PATH:~/.local/bin source ~/.profile + + - Note: On OS X the path is different: `~/Library/Python/2.7/bin` + +- Go to the docs directory in the Project X-Ray repo: + + cd ~/github-repos/prjxray/docs + +- Run pipenv to install the Sphinx environment: + + pipenv install + +- Activate the shell: + + pipenv shell + +- Run the HTML build checker, and check for _errors_: + + make html + +- Run the link checker, and check for _warnings_: + + make linkcheck + +- To leave the shell, type: `exit`. + +## Perform more comprehensive testing on your own staging doc site + +If your changes are more comprehensive, you should do a full test of your fork +of the docs before sending a pull request to the Project X-Ray repo. You can +test your fork by viewing the docs on your own copy of the Read the Docs +build. + +Follow these steps to create your own staging doc site on Read the Docs (RtD): + +- Sign up for a RtD account here: + [https://readthedocs.org/](https://readthedocs.org/) +- Go to your [RtD connected + services](https://readthedocs.org/accounts/social/connections/), click + **Connect to GitHub**, and connect RtD to your GitHub account. (If you + decide not to do this, you'll need to import your project manually in the + following steps.) +- Go to [your RtD dashboard](https://readthedocs.org/dashboard/). +- Click **Import a Project**. +- Add your GitHub fork of the Project X-Ray project. Give your doc site a + **name** that distinguishes it from the canonical Project X-Ray docs. For + example, `your-username-prjxray` +- Make your doc site **protected**. See the [RtD guide to privacy + levels](http://docs.readthedocs.io/en/latest/privacy.html). + 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 + looking for the canonical Project X-Ray docs. +- Set RtD to build from your branch, rather than from master. This ensures + that the content you see on your doc site reflect your latest updates: + - On the RtD dashboard, go to **Admin > Advanced Settings.** + - Add the name of your branch in **Default branch**. This is the + branch that the "latest" build config points to. If you leave this field + empty, RtD uses `master` or `trunk`. + +- RtD now builds your doc site, based on the contents in your Project X-Ray + fork. +- See the [RtD getting-started + guide](https://docs.readthedocs.io/en/latest/getting_started.html#import-docs) + for more info. + +# 3. Send a pull request + +Follow your standard GitHub process to send a pull request to the Project X-Ray +repo. See the GitHub guide to [creating a pull request from a +fork](https://help.github.com/articles/creating-a-pull-request-from-a-fork/). From b8a4ef8540952d5fa7399a0a6d07f33bfcda526a Mon Sep 17 00:00:00 2001 From: Sarah Maddox Date: Mon, 7 May 2018 11:59:12 +1000 Subject: [PATCH 4/5] Updated the contribution guidelines by running update-contributing.py. Signed-off-by: Sarah Maddox --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5cce82a5..61d2b4df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,6 +79,11 @@ master: git rebase --signoff upstream/master +### Contributing to the docs + +In addition to the above contribution guidelines, see the guide to +[updating the Project X-Ray docs](UPDATING-THE-DOCS.md). + From f859275fda1f124c7aba0a51e921ab7ae1002581 Mon Sep 17 00:00:00 2001 From: Sarah Maddox Date: Mon, 7 May 2018 12:14:02 +1000 Subject: [PATCH 5/5] Fixes some formatting in the guide to updating docs. Signed-off-by: Sarah Maddox --- UPDATING-THE-DOCS.md | 64 ++++++++++++++++++++++---------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/UPDATING-THE-DOCS.md b/UPDATING-THE-DOCS.md index 40f9537f..f9521548 100644 --- a/UPDATING-THE-DOCS.md +++ b/UPDATING-THE-DOCS.md @@ -43,47 +43,46 @@ Sphinx and all the necessary plugins are installed: Steps in detail, on Linux: -- Install pip: +1. Install pip: - sudo apt install python-pip + sudo apt install python-pip -- Install pipenv - see the +1. Install pipenv - see the [pipenv installation guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv): - pip install pipenv + pip install pipenv -- Add pipenv to your path, as recommended in the +1. Add pipenv to your path, as recommended in the [pipenv installation - guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv): - - - On Linux, add this in your ~/.profile file: + guide](http://pipenv.readthedocs.io/en/latest/install/#installing-pipenv). On + 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` -- 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 -- Run pipenv to install the Sphinx environment: +1. Run pipenv to install the Sphinx environment: - pipenv install + pipenv install -- Activate the shell: +1. Activate the shell: - pipenv shell + pipenv shell -- Run the HTML build checker, and check for _errors_: +1. Run the HTML build checker, and check for _errors_: - make html + make html -- Run the link checker, and check for _warnings_: +1. Run the link checker, and check for _warnings_: - make linkcheck + make linkcheck -- To leave the shell, type: `exit`. +1. To leave the shell, type: `exit`. ## Perform more comprehensive testing on your own staging doc site @@ -94,33 +93,34 @@ build. Follow these steps to create your own staging doc site on Read the Docs (RtD): -- Sign up for a RtD account here: +1. Sign up for a RtD account here: [https://readthedocs.org/](https://readthedocs.org/) -- Go to your [RtD connected +1. Go to your [RtD connected services](https://readthedocs.org/accounts/social/connections/), click **Connect to GitHub**, and connect RtD to your GitHub account. (If you decide not to do this, you'll need to import your project manually in the following steps.) -- Go to [your RtD dashboard](https://readthedocs.org/dashboard/). -- Click **Import a Project**. -- Add your GitHub fork of the Project X-Ray project. Give your doc site a +1. Go to [your RtD dashboard](https://readthedocs.org/dashboard/). +1. Click **Import a Project**. +1. Add your GitHub fork of the Project X-Ray project. Give your doc site a **name** that distinguishes it from the canonical Project X-Ray docs. For - example, `your-username-prjxray` -- Make your doc site **protected**. See the [RtD guide to privacy + example, `your-username-prjxray`. +1. Make your doc site **protected**. See the [RtD guide to privacy levels](http://docs.readthedocs.io/en/latest/privacy.html). 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 looking for the canonical Project X-Ray docs. -- Set RtD to build from your branch, rather than from master. This ensures +1. Set RtD to build from your branch, rather than from master. This ensures that the content you see on your doc site reflect your latest updates: - - On the RtD dashboard, go to **Admin > Advanced Settings.** + - On [your RtD dashboard](https://readthedocs.org/dashboard/), + open **your project**, then go to **Admin > Advanced Settings.** - Add the name of your branch in **Default branch**. This is the branch that the "latest" build config points to. If you leave this field empty, RtD uses `master` or `trunk`. -- RtD now builds your doc site, based on the contents in your Project X-Ray +1. RtD now builds your doc site, based on the contents in your Project X-Ray fork. -- See the [RtD getting-started +1. See the [RtD getting-started guide](https://docs.readthedocs.io/en/latest/getting_started.html#import-docs) for more info.