From 46984c9d039865b33284695c18cfb67b0419ed08 Mon Sep 17 00:00:00 2001 From: lethosor Date: Wed, 11 Aug 2021 19:14:36 -0400 Subject: [PATCH] Split docs conventions into subsections, add links to documentation on links --- docs/Documentation.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/Documentation.rst b/docs/Documentation.rst index 5e1f8c599..be4511ba8 100644 --- a/docs/Documentation.rst +++ b/docs/Documentation.rst @@ -38,6 +38,9 @@ there are a few important standards for completeness and consistent style. Trea this section as a guide rather than iron law, match the surrounding text, and you'll be fine. +Command documentation +--------------------- + Each command should have a short (~54 character) help string, which is shown by the `ls` command. For scripts, this is a comment on the first line (the comment marker and whitespace is stripped). For plugins it's the second @@ -80,6 +83,9 @@ Try to keep lines within 80-100 characters, so it's readable in plain text in the terminal - Sphinx (our documentation system) will make sure paragraphs flow. +Command usage +------------- + If there aren't many options or examples to show, they can go in a paragraph of text. Use double-backticks to put commands in monospaced font, like this:: @@ -103,6 +109,9 @@ describe the effect:: ``resume all`` Resumes all suspended constructions. +Links +----- + If it would be helpful to mention another DFHack command, don't just type the name - add a hyperlink! Specify the link target in backticks, and it will be replaced with the corresponding title and linked: e.g. ```autolabor``` @@ -118,6 +127,17 @@ section like this:: Add link targets if you need them, but otherwise plain headings are preferred. Scripts have link targets created automatically. +Note that the DFHack documentation is configured so that single backticks (with +no prefix or suffix) produce links to internal link targets, such as the +``autolabor`` target shown above. This is different from the reStructuredText +default behavior of rendering such text in italics (as a reference to a title). +For alternative link behaviors, see: + +- `The reStructuredText documentation on roles `__ +- `The reStructuredText documentation on external links `__ +- `The Sphinx documentation on roles `__ + + - ``:doc:`` is useful for linking to another document Required dependencies =====================