How to build documentation

This pages describes the process for building documentation for a new or existing release.

• Check out the tag or commit for the relevant release, and make sure your local clone is clean:

  traits$ git checkout 6.0.0
  traits$ git clean -ffxd
  

• Build the development environment:

  traits$ python etstool.py install
  

• Build the documentation:

  traits$ python etstool.py docs
  

  You should see lots of output ending with something like this:

  build succeeded.
  
  The HTML pages are in build/html.
  

• Test the built documentation locally. If you try to view the files directly in a browser (with the file:// protocol), you may run into CORS policy warnings when searching. For example, under Chrome, I see warnings with a message resembling "Cross origin requests are only supported for protocol schemes: http, data, chrome, chrome-extension, https.". Instead, you can set up a local server:

  traits$ cd docs/build/html/
  html$ python -m http.server
  Serving HTTP on :: port 8000 (http://[::]:8000/) ...
  

  Now navigate to http://localhost:8000/ in a browser window to browse the documentation. If you can, it's worth turning on JavaScript console warnings while you browse. Once you're happy, do a Ctrl-C to quit the server process, and return to the repository root directory.

  ^C
  Keyboard interrupt received, exiting.
  html$ cd ../../..
  

• Check out the gh-pages branch, make sure it's up to date, and create a new branch for the documentation updates. Note that this will bring in the built documentation as uncommitted changes.

  traits$ git checkout gh-pages
  traits$ git checkout -b gh-pages-update
  

  A git status should now show the docs directory containing the new documentation.

  traits$ git status
  On branch gh-pages-update
  Untracked files:
    (use "git add <file>..." to include in what will be committed)
  	docs/
  
  nothing added to commit but untracked files present (use "git add" to track)
  

• For a new feature release, move the existing documentation for the old release into a subdirectory with name <major>.<minor> (e.g., 5.2). For a minor documentation update, delete the existing files in the top-level directory (but not docs, and not directories corresponding to older releases):

  traits$ rm *
  traits$ rm -r traits_api_reference traits_user_manual traits_tutorial _*
  

• Move the newly-built documentation from docs to the top level of the repository:

  traits$ mv -i docs/build/html/* .
  traits$ rm -r docs/
  

• Commit the changes, and make a pull request; be sure to specify gh-pages as the target branch for that pull request.