wiki:ReviewingDocumentation

Reviewing and Adding Documentation

Some reasons the documentation need help include if:

  • the explanations are unclear
  • the examples don't work or have become outdated
  • the overall structure or the order in which information is presented is unintuitive
  • examples for major concepts are missing

Note that the example and howto documentation on the website may be outdated, as they are only updated from trunk on releases.

Editing example and howto documentation

  1. if you haven't already, create your Twisted work environment.
  1. make sure you have the latest version of the code
  1. Edit away!

The documentation lives in reStructuredText (.rst) files in subdirectories of Twisted/docs/. Twisted uses the document generator sphinx to generate the html files you see on the web from these .rst files. After adding your changes, it's important to review your changes for correctness and to preview how they will look on the website.

  1. Previewing with sphinx

For example, if I made changes to Twisted/docs/core/howto/choosing-reactor.rst, I should

. build/bin/activate  # only necessary once; 'build' is the virtualenv name used on the TwistedDevelopment wiki page
python bin/admin/build-docs .

This generates Twisted/doc/core/howto/choosing-reactor.html, which you can view in a web browser via the URL

file:///path/to/Twisted/doc/core/howto/choosing-reactor.html

If everything looks good, submit a patch to the .rst as described here.

Editing API Docs

The API docs are generated from the doc strings in the code by pydoctor, so to update what will be displayed in the API docs just update the doc strings. After making your changes, generate a test set of API docs to preview how they will look.

  1. if you haven't already, create your Twisted work environment.
  1. make sure you have the latest version of the code
  1. Edit away! Be sure to adhere to the docstring guidelines in the Twisted coding standard.
  1. Preview your changes

Generate the docs with the build-apidocs admin script like so:

. build/bin/activate  # only necessary once; 'build' is the virtualenv name used on the TwistedDevelopment wiki page
python bin/admin/build-apidocs src apidocs

The above produces a folder called apidocs in your current working directory. You can then browse from the entry points to the docs in a web browser via the URL

file:///path/to/apidocs/index.html

If everything looks good, submit a patch as described here.

More

see also DocumentationAnalysis from an old Twisted documentation sprint.

Last modified 5 months ago Last modified on 05/22/2017 05:43:54 PM