publish.rst

Publish your project

The final step is to publish your project. This section assumes you're using GitHub; any differences with GitLab or other services are minor.

Push your project to a Git host

Initialise the project as a Git repository:

git init .

Add a .gitignore file, containing at least:

_build
sphinxenv

and any other file patterns you want to exclude.

For the sake of repeatability, collect all the Python dependencies in the environment into a requirements.txt file:

pip freeze > requirements.txt

Add a readme or licence file according to taste.

Create a repository at the Git hosting service, commit your local changes and push.

Connect the project to Read the Docs

For this to work, your Git project must be public, unless you have a paid-for Read the Docs subscription.

Log in or sign up at https://readthedocs.org.

Connect your RTD account to your GitHub account - check this at https://readthedocs.org/accounts/social/connections/.

Use Import a project to select your documentation repository, or else enter its details manually at https://readthedocs.org/dashboard/import/.

When you hit Next, RTD will set up a webhook on your repository (Repository > Settings > Webhooks). Now any new commits landing in the repository will trigger a build on RTD, and the documentation will be available to view.

Adjust documentation settings

The project dashboard has an Admin view, with some useful settings. Some of these are obvious, others that are worth checking include:

• Advanced
  • Single version: useful if this is a standalone documentation set, rather than something that's part of a versioned code-base.
  • Build pull requests for this project: if you expect contributions and would like contributors' pull requests to create their own builds.
  • Documentation type: set this to SphinHTMLDir, so that your pages' URLs don't include the .html extension.
• Integrations: to check the GitHub webhook.