Skip to content

Latest commit

 

History

History
65 lines (39 loc) · 2.87 KB

ReviewingDocumentation.mediawiki

File metadata and controls

65 lines (39 loc) · 2.87 KB

Table of Contents

Reviewing and Adding Documentation

The documentation may need help if: 

 * Explanations are unclear
 * 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 it is only updated from trunk on releases. The latest build on Read the Docs reflects current trunk.

Editing example and howto documentation

These narrative docs live in reStructuredText (`.rst`) files in subdirectories of 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. If you haven't already, [wiki:TwistedDevelopment#Creatingyourworkenvironment].

2. Make sure you have the latest version of the code

3. Edit away!

4. Preview your changes with Sphinx

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

This generates `docs/_build/core/howto/choosing-reactor.html`, which you can view in a web browser with the command:

If everything looks good, submit a patch to the `.rst` as described [wiki:TwistedDevelopment#SubmittingaPatch].

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, [wiki:TwistedDevelopment#Creatingyourworkenvironment].

2. Make sure you have the latest version of the code

3. Edit away! Be sure to adhere to the docstring guidelines in the Twisted coding standard.

4. Preview your changes with pydoctor

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

The above produces a folder called `apidocs` in your current working directory. You can then open the docs in a web browser with the command:

If everything looks good, submit a patch as described [wiki:TwistedDevelopment#SubmittingaPatch].

More

See also [wiki:DocumentationAnalysis] from an old Twisted documentation sprint.