Changes between Version 9 and Version 10 of ReviewingDocumentation


Ignore:
Timestamp:
05/22/2017 05:43:54 PM (7 months ago)
Author:
habnabit
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ReviewingDocumentation

    v9 v10  
    1111=== Editing example and howto documentation ===
    1212
    13 1. if you haven't already, check out a copy of the Twisted svn repository
    14 
    15 `svn checkout svn://svn.twistedmatrix.com/svn/Twisted/trunk ~/my-code-dir/Twisted/trunk`
     131. if you haven't already, [wiki:TwistedDevelopment#Creatingyourworkenvironment create your Twisted work environment].
    1614
    17152. make sure you have the latest version of the code
    1816
    19 `cd ~/my-code-dir/Twisted/trunk`[[BR]]
    20 
    21 `svn update`
    22 
    23173. Edit away!
    2418
    25 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.
     19The documentation lives in [http://docutils.sourceforge.net/rst.html reStructuredText] (`.rst`) files in subdirectories of `Twisted/docs/`. Twisted uses the document generator [https://sphinx.readthedocs.io/en/stable/ 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.
    2620
    27 4. Previewing with lore
     214. Previewing with sphinx
    2822
    29 For example, if I made changes to `trunk/doc/core/howto/choosing-reactor.xhtml`, I should[[BR]]
     23For example, if I made changes to `Twisted/docs/core/howto/choosing-reactor.rst`, I should
    3024
    31 `cd ~/my-code-dir/Twisted/trunk/doc/core/howto`[[BR]]
     25{{{
     26. build/bin/activate  # only necessary once; 'build' is the virtualenv name used on the TwistedDevelopment wiki page
     27python bin/admin/build-docs .
     28}}}
    3229
    33 `lore choosing-reactor.xhtml`
     30This generates `Twisted/doc/core/howto/choosing-reactor.html`, which you can view in a web browser via the URL
    3431
    35 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.
     32`file:///path/to/Twisted/doc/core/howto/choosing-reactor.html`
    3633
    37 This generates `choosing-reactor.html`, which you can view in a web browser via the URL
    38 
    39 `file:///path/to/my-code-dir/Twisted/trunk/doc/core/howto/choosing-reactor.html`
    40 
    41 If everything looks good, submit a patch to the xhtml as described [wiki:TwistedDevelopment#SubmittingaPatch here].
     34If everything looks good, submit a patch to the `.rst` as described [wiki:TwistedDevelopment#SubmittingaPatch here].
    4235
    4336=== Editing API Docs ===
    4437
    45 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.
     38The API docs are generated from the doc strings in the code by [https://github.com/twisted/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.
    4639
    47 1. if you haven't already, check out a copy of the Twisted svn repository
    48 
    49 `svn checkout svn://svn.twistedmatrix.com/svn/Twisted/trunk ~/my-code-dir/Twisted/trunk`
     401. if you haven't already, [wiki:TwistedDevelopment#Creatingyourworkenvironment create your Twisted work environment].
    5041
    51422. make sure you have the latest version of the code
    5243
    53 `cd ~/my-code-dir/Twisted/trunk`[[BR]]
    54 
    55 `svn update`
    56 
    57 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].
     443. Edit away! Be sure to adhere to the docstring guidelines in the [https://twistedmatrix.com/documents/current/core/development/policy/ Twisted coding standard].
    5845
    59464. Preview your changes
    6047
    61 To generate API docs you need to have installed:
    62  * [https://launchpad.net/pydoctor pydoctor] - API documentation tool for Python written to be used with Twisted
    63  * [http://epydoc.sourceforge.net/ Epydoc] - an API documentation tool on which pydoctor depends
    64  * [https://launchpad.net/divmod.org nevow] - pydoctor's HTML generation side uses Nevow templates
     48Generate the docs with the build-apidocs admin script like so:
    6549
    66 Once everything is installed, generate the docs with the build-apidocs admin script like so:
    67 
    68 `bin/admin/build-apidocs /path/to/my-code-dir/Twisted/trunk apidocs`
     50{{{
     51. build/bin/activate  # only necessary once; 'build' is the virtualenv name used on the TwistedDevelopment wiki page
     52python bin/admin/build-apidocs src apidocs
     53}}}
    6954
    7055The 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
     
    7459If everything looks good, submit a patch as described [wiki:TwistedDevelopment#SubmittingaPatch here].
    7560
    76 === Editing man pages ===
    77 
    78 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`:
    79 
    80 {{{
    81 from twisted.python.filepath import FilePath
    82 dir = FilePath('doc/core/man')
    83 from twisted.python._release import ManBuilder
    84 m = ManBuilder()
    85 m.build(dir)
    86 }}}
    87 
    88 you can then `lore` the resulting xhtml files as described [ReviewingDocumentation#Editingexampleandhowtodocumentation above] to generate html.
    89 
    9061=== More ===
    9162see also [wiki:DocumentationAnalysis DocumentationAnalysis] from an old Twisted documentation sprint.