From da075192b6858be8210682c78e71f97f18759291 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 19 Mar 2024 11:18:51 -0400 Subject: [PATCH] Move markup concerns from style to markup --- documentation/markup.rst | 38 +++++++++++++++++++++++++++++++++++ documentation/style-guide.rst | 37 +++------------------------------- 2 files changed, 41 insertions(+), 34 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index e457a525f..c7a5a5ac4 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -52,6 +52,22 @@ language, this will not take too long. Documentation `_. +Use of whitespace +----------------- + +All reST files use an indentation of 3 spaces; no tabs are allowed. The +maximum line length is 80 characters for normal text, but tables, deeply +indented code samples and long links may extend beyond that. Code example +bodies should use normal Python 4-space indentation. + +Make use of multiple blank lines where applicable to clarify the structure of +the reST file. Extra blank lines help group sections together to make the +organization of the file clearer. + +A sentence-ending period may be followed by one or two spaces. While reST +ignores the second space, it is customarily put in by some users, for example +to aid Emacs' auto-fill mode. + Paragraphs ---------- @@ -289,6 +305,28 @@ There are some problems one commonly runs into while authoring reST documents: separated from the surrounding text by non-word characters, you have to use an escaped space to get around that. + +Typographic conventions +======================= + +Big *O* notation +---------------- + +Big *O* notation is used to describe the performance of algorithms. + +Use italics for the big *O* and variables. For example: + +======================== ==================== +reStructuredText Rendered +======================== ==================== +``*O*\ (1)`` *O*\ (1) +``*O*\ (log *n*)`` *O*\ (log *n*) +``*O*\ (*n*)`` *O*\ (*n*) +``*O*\ (*n* log *n*)`` *O*\ (*n* log *n*) +``*O*\ (*n*\ :sup:`2`)`` *O*\ (*n*\ :sup:`2`) +======================== ==================== + + .. _additional-markup-constructs: Additional markup constructs diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 2e5a1c953..0078d670e 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -4,26 +4,12 @@ Style guide =========== -.. highlight:: rest +.. highlight:: rest -This document describes the style guide for our documentation. +This page describes the linguistic style guide for our documentation. +For markup details in reST files, see :ref:`markup`. -Use of whitespace -================= - -All reST files use an indentation of 3 spaces; no tabs are allowed. The -maximum line length is 80 characters for normal text, but tables, deeply -indented code samples and long links may extend beyond that. Code example -bodies should use normal Python 4-space indentation. - -Make generous use of blank lines where applicable; they help group things -together. - -A sentence-ending period may be followed by one or two spaces; while reST -ignores the second space, it is customarily put in by some users, for example -to aid Emacs' auto-fill mode. - Footnotes ========= @@ -264,20 +250,3 @@ errors ("I made a mistake, therefore the docs must be wrong ..."). Typically, the documentation wasn't consulted until after the error was made. It is unfortunate, but typically no documentation edit would have saved the user from making false assumptions about the language ("I was surprised by ..."). - -Big *O* notation -================ - -Big *O* notation is used to describe the performance of algorithms. - -Use italics for the big *O* and variables. For example: - -======================== ==================== -reStructuredText Rendered -======================== ==================== -``*O*\ (1)`` *O*\ (1) -``*O*\ (log *n*)`` *O*\ (log *n*) -``*O*\ (*n*)`` *O*\ (*n*) -``*O*\ (*n* log *n*)`` *O*\ (*n* log *n*) -``*O*\ (*n*\ :sup:`2`)`` *O*\ (*n*\ :sup:`2`) -======================== ====================