Skip to content

Latest commit

 

History

History
107 lines (67 loc) · 2.92 KB

README.WRITING_RST.rst

File metadata and controls

107 lines (67 loc) · 2.92 KB

THINGS TO CONSIDER WHEN WRITING VARNISH RST DOCUMENTATION

Inline Markup

Please try to be consistent with inline markup and fix places which do not follow the style:

  • VCL language and other literals as literal
  • placeholders and emphasis as emphasis
  • no interpreted text except where it actually is that
  • exception: Links to manpages outside varnish as man(section)

  • use code blocks for:

    Examples and

other code

References are tricky

To build html documentation, we want to create cross-document cross-references using:

:ref:`reference name`

Trouble is that rst2man and rst2pdf working on individual files cannot parse ref roles to anything outside the current rst file, so we need to differentiate link targets depending on the kind of documentation:

  • set link targets on the top of documents ending up in man-pages following the manpage naming scheme, e.g.:

    .. _varnishd(1):

  • set link targets for important paragraphs following the scheme ref-doc-section, for instance:

    .. _ref-varnishd-opt_T:

    These can be referenced from other documents making up the html documentation, but not from stand-alone documents (like man-pages).

  • in all documents which are used to create man-pages, add the following definition at the top:

    .. role:: ref(emphasis)

    This will allow the use of ref in a compatible manner, IF references follow the man-page naming scheme

  • to be compatible both with sphinx and rst2man, use implicit link targets in stand-alone documents, like this one creating References are tricky:

    `References are tricky`_

Document Structure

While RST supports a great deal of flexibility for adornments of titles and section headers, we should adhere to a consistent style to avoid breaking the document structure unintentionally.

Within the Varnish-Cache project, we should use these characters:

  • Over and underline = for document titles
  • Over and underline - for document subtitles
  • Underline = for sections
  • Underline - for subsection
  • Underline ~ for subsubsections

This is in line with the example in https://docutils.sourceforge.io/docs/user/rst/quickstart.html#sections

HISTORY

This README was initially started by Nils Goroll.

COPYRIGHT

This document is licensed under the same licence as Varnish itself. See LICENCE for details.

  • Copyright 2015,2016,2019,2024 UPLEX - Nils Goroll Systemoptimierung