|Version 1 (modified by jesstess, 4 years ago)|
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 svn on releases.
Editing example and howto documentation
1. 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
3. Edit away!
The documentation lives in xhtml files in subdirectories of trunk/doc/. Twisted uses the document generator 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
So, for example, if I made changes to trunk/doc/core/howto/choosing-reactor.xhtml, I should
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 on.
This generates choosing-reactor.html, which you can view in a web browser with the URL
If everything looks good, submit a patch 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.
To generate API docs you need to have installed:
- pydoctor - API documentation tool for Python written to be used with Twisted
- Epydoc - an API documentation tool on which pydoctor depends
- nevow - pydoctor's HTML generation side uses Nevow templates
Once everything is installed, generate the docs with a command like:
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 with the URL
If everything looks good, submit a patch as described here