readthedocs

When developing on your own fork of NetworkX, it can be helpful to have the documentation built on each commit. Read the Docs is a service providing this functionality that interfaces nicely to GitHub.

When you submit a pull request that heavily modifies user documentation, you may choose to provide a link to the built documentation. This allows reviewers to easily see rendered changes and makes sure that nothing in the build process was broken.

Generally, we recommend that you configure Read the Docs such that your NetworkX documentation is "Protected" rather than "Public". When "Protected", the documentation will not be indexed by search engines. This will keep searches for NetworkX-related content pointing to the primary documentation rather than some fork's documentation.

To enable auto-building of NetworkX documentation on your fork:

1. Create an account on Read the Docs.
2. Connect your account to GitHub by clicking the "Connect to GitHub" button. You can also modify your Social Connections and add GitHub.
3. Import your NetworkX fork from GitHub as a project. A suggested name for your project is username-networkx where username would be replaced with your GitHub username. We assume that name in the following.
4. Navigate to the project username-networkx, click the "Admin" button, and then select "Advanced Settings" in the left pane.
5. Check the box "Install your project inside a virtualenv using setup.py install".
6. Type "doc/requirements.txt" into the "Requirements file" field.
7. Type "doc/source/conf.py" into the "Python configuration file".
8. Set the "Privacy Level" to "Protected".
9. Check the box "Give the virtual environment access to the global site-packages dir".
10. Click "Submit".
11. In the left pane, click "Versions" and activate auto-builds for any branch you want. "latest" corresponds to the latest released version and can probably be unchecked since it is not useful for development.

With the above, you can manually initiate builds of the NetworkX documentation on any branch of your fork. To make builds happen automatically with each commit on GitHub, you need to instruct GitHub to inform ReadTheDocs of changes:

1. On GitHub, navigate to your NetworkX fork and click on "Settings".
2. In the sidebar, click on "Web Hooks & Services", then find and click on the "ReadTheDocs" service.
3. Check the "Active" setting and click "Update Settings".

Now each commit to an active branch on ReadTheDocs will automatically initiate a documentation rebuild.

Note that if the advanced settings are not set, then documentation builds will fail to import Matplotlib. If, after enabling the virtualenv and global site-packages, you see build errors such as "Could not import extension numpydoc (exception: No module named numpydoc)", then the build environment is stale and should be wiped. To do this, click on "Versions" at the top. Find the branch of interest, click the "Wipe" button, and then click "Wipe Version". Then, re-initiate a doc build.