Readthedocs support

blaflamme edited this page Nov 27, 2011 · 12 revisions

We'd like to set up a Read the Docs instance for all Pylons Projects github-hosted projects (Pyramid, Pylons, all Pyramid add-ons, all Pylons project libriaries such as Colander and Deform). The system should have the following features:

  • If we choose to run our own RTD instance, we should create a buildout for it.

  • Get all docs under Pylons Project namespace

  • Point out to the namespace

  • Should show docs for all existing tags for each package.

  • Automatically publish new revision of docs when a tag is made to git

  • Automatically update a dev version of the docs for each package every X minutes, or on each commit?

Update documentation procedure

  • Connect to, and create an account if you don't have one
  • Verify if the project you're looking for is already updated
  • Fork the project to your own account, i.e. pyramid_beaker
  • Remove entry for _themes in .gitmodule or .gitmodule itself if _themes the only one listed
  • Run git rm --cached docs/_themes (or _themes depending of the package)
  • Remove docs/_themes directory if it exists
  • Add docs/_themes to .gitignore and/or _themes to docs/.gitignore
  • In Makefile remove any entries for _themes
  • Add this snippet in under Options for HTML Output
  • Add an rtd.txt file in the project root with this content; repoze.sphinx.autointerface and/or any other required package
  • Test out the building process in docs directory with this command; make clean html
  • Send a pull request

Next steps

  • fix urls/links in distribution docs which point t other pylons project projects