8000 Move markup concerns from style to markup by nedbat · Pull Request #1292 · python/devguide · GitHub
[go: up one dir, main page]
Skip to content

Move markup concerns from style to markup #1292

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 20, 2024
Merged

Move markup concerns from style to markup #1292

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Move markup concerns from style to markup
  • Loading branch information
@nedbat
nedbat committed Mar 19, 2024
commit da075192b6858be8210682c78e71f97f18759291
38 changes: 38 additions & 0 deletions documentation/markup.rst
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FTR this page was initially copied from https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html. I don't think your additions are a problem though, since it has already diverged from the original over the years.

Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,22 @@ language, this will not take too long.
Documentation <https://docutils.sourceforge.io/rst.html>`_.


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
----------

Expand Down Expand Up @@ -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
Expand Down
37 changes: 3 additions & 34 deletions documentation/style-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
=========

Expand Down Expand Up @@ -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`)
======================== ====================
0