Skip to content

How to build documentation

Mark Dickinson edited this page Nov 29, 2021 · 5 revisions

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/
    
  • Update the contents of the .currentversion file if necessary. (It should only need updating for new feature releases, not for minor updates.)

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

Clone this wiki locally