Opened 4 years ago

Closed 18 months ago

#6905 enhancement closed invalid (invalid)

Re-write the (currently HTML) documentation standard for Sphinx

Reported by: Julian Berman Owned by:
Priority: normal Milestone: Lore to Sphinx
Component: core Keywords: documentation
Cc: khorn, Hynek Schlawack Branch: doc-standard-6905
branch-diff, diff-cov, branch-cov, buildbot
Author: julian


The documentation standard at docs/projects/core/policy/doc-standard.rst is written about XHTML.

Some of its sections are relevant for Sphinx and probably should be ported over.

Other minor sphinx related style points that probably would be nice to address are which directives to use for code snippets (e.g. using the sphinx doctest directives means that we'd gain the ability to doctest sections in the docs), what hierarchy to use for heading sections, which directive[s] to use for argument / return types.

Change History (13)

comment:1 Changed 4 years ago by khorn

Cc: khorn added

comment:2 Changed 4 years ago by khorn

Included should be guidelines on how to use Sphinx's versionadded, versionchanged, and deprecated directives.


Another thing that would be useful to have would be guidelines on how to review documentation changes.

comment:3 Changed 4 years ago by khorn

Re using Sphinx doctest directives, there are pros and cons to using them. They clutter up the markup quite a bit, and well...doctest. :/

A better solution is probably to keep code sample in external .py files and include them using literalinclude (keep in mind you can include only part of a file if you want), and then have tests written on those external files.

This obviously requires more setup outside of Sphinx though.

comment:4 Changed 4 years ago by Hynek Schlawack

Cc: Hynek Schlawack added

I would like to see the following things clarified so they’re consistent throughout the project:

  • which bullet type to use (I prefer - over *),
  • how many empty lines where (I like two above new sections, one under it and two before code snippets),
  • mention semantic line feeds that already are project standard (at least I couldn’t find them on cursory reading),

and finally: what is

:LastChangedDate: $LastChangedDate$
:LastChangedRevision: $LastChangedRevision$
:LastChangedBy: $LastChangedBy$”

do we still need/use it (I asked a few times on IRC but never got a response)?

comment:5 Changed 4 years ago by Jean-Paul Calderone

mention semantic line feeds that already are project standard (at least I couldn’t find them on cursory reading)

It's in the 'XHTML Layout' section of docs/projects/core/development/policy/doc-standard.rst

comment:6 Changed 4 years ago by Julian Berman

Just to note it here as well, actual examples of how to intersphinx-and-regular-sphinx link to sections and objects would be helpful to those who haven't used sphinx much.

comment:7 Changed 4 years ago by julian

Author: julian
Branch: branches/doc-standard-6905

(In [41441]) Branching to doc-standard-6905.

comment:8 Changed 4 years ago by Richard Wall

It might be worth noting the importance / significance of the ".. toctree::" blocks and their contents.

These don't seem to be used / visible in the locally rendered docs (ie cd docs; make html)

But they are important for rendering the breadcrumb navigation links on Readthedocs.

See #6940 for an example of me making this mistake in some new Twisted Names documentation.

comment:9 Changed 4 years ago by hawkowl

Milestone: Lore to Sphinx

comment:10 Changed 4 years ago by Glyph

hynek sent me here to declare my preference for AP-stylebook-style usage of em dashes. This is unusual, but typographically I prefer to give the long emdash some breathing room.

comment:11 Changed 4 years ago by Adi Roiban

I have updated wiki page to link to Sphinx ReST primer.

Maybe we can merge doc-standard with writing-standard as I think that they should be read together.

I don't think that we should duplicate documentation for ReST and Sphinx, but rather just add Twisted specific directives and conventions.


comment:12 Changed 18 months ago by Glyph

Branch: branches/doc-standard-6905doc-standard-6905

comment:13 Changed 18 months ago by Glyph

Resolution: invalid
Status: newclosed

There might be something more to do here, but doc-standard is gone, and there are references to ReST rather than HTML everywhere now, so the meat of this is complete and if we want to re-integrate the material in this branch it'll need to be somewhere else. Closing.

Note: See TracTickets for help on using tickets.