== 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, check out a copy of the Twisted svn repository

`svn checkout svn://svn.twistedmatrix.com/svn/Twisted/trunk ~/my-code-dir/Twisted/trunk`

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

`cd ~/my-code-dir/Twisted/trunk`[[BR]]

`svn update`

3. Edit away!

The documentation lives in xhtml files in subdirectories of `trunk/doc/`. Twisted uses the document generator [wiki:TwistedLore lore] to generate the html files you see on the web from these xhtml files. After adding your changes to an xhtml file, it's important to review your changes for correctness and to preview how they will look on the website.

4. Previewing with lore

For example, if I made changes to `trunk/doc/core/howto/choosing-reactor.xhtml`, I should[[BR]]

`cd ~/my-code-dir/Twisted/trunk/doc/core/howto`[[BR]]

`lore choosing-reactor.xhtml`

lore expects a template file in the directory from which you execute the command. If there isn't a `template.tpl` file in your directory, copy one from a directory that does have one, like `doc/core/howto`, or run lore from a directory that does have one.

This generates `choosing-reactor.html`, which you can view in a web browser via the URL

`file:///path/to/my-code-dir/Twisted/trunk/doc/core/howto/choosing-reactor.html`

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

=== Editing API Docs ===

The API docs are generated from the doc strings in the code by [http://codespeak.net/~mwh/pydoctor/ 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, check out a copy of the Twisted svn repository

`svn checkout svn://svn.twistedmatrix.com/svn/Twisted/trunk ~/my-code-dir/Twisted/trunk`

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

`cd ~/my-code-dir/Twisted/trunk`[[BR]]

`svn update`

3. Edit away! Be sure to adhere to the docstring guidelines in the [http://twistedmatrix.com/trac/browser/trunk/doc/core/development/policy/coding-standard.xhtml?format=raw Twisted coding standard].

4. Preview your changes

To generate API docs you need to have installed: 
 * [http://codespeak.net/~mwh/pydoctor/ pydoctor] - API documentation tool for Python written to be used with Twisted
 * [http://epydoc.sourceforge.net/ Epydoc] - an API documentation tool on which pydoctor depends
 * [http://www.divmod.org/trac/wiki/DivmodNevow nevow] - pydoctor's HTML generation side uses Nevow templates

Once everything is installed, generate the docs with a command like:[[BR]]
`pydoctor --quiet --make-html --system-class pydoctor.twistedmodel.TwistedSystem --add-package /path/to/my-code-dir/Twisted/trunk/twisted`

This 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 [wiki:TwistedDevelopment#SubmittingaPatch here]

=== Editing man pages ===

Twisted man pages live in `doc/<subproject>/man`. The man pages are `lore`'d as part of a release to generate html files, so if you are reviewing man pages you should make sure they generate valid html through `lore`. The easiest way to do this is to steal from `twisted.python._release`. To, for example, generate xhtml from the troff files in `doc/core/man`:

{{{
from twisted.python.filepath import FilePath
dir = FilePath('doc/core/man')
from twisted.python._release import ManBuilder
m = ManBuilder()
m.build(dir)
}}}

you can then `lore` the resulting xhtml files as described [ReviewingDocumentation#Editingexampleandhowtodocumentation above] to generate html.

=== More ===
see also [wiki:DocumentationAnalysis DocumentationAnalysis] from an old Twisted documentation sprint.