launchpad-reviewers team mailing list archive

[Colin Watson <mp+411735@xxxxxxxxxxxxxxxxxx>]

Colin Watson has proposed merging ~cjwatson/launchpad:dev-guides-formatting into launchpad:master.

Commit message:
Improve some Sphinx formatting

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~cjwatson/launchpad/+git/launchpad/+merge/411735
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~cjwatson/launchpad:dev-guides-formatting into launchpad:master.

diff --git a/doc/guides/architecture.rst b/doc/guides/architecture.rst
index 239b7c8..cc5c143 100644
--- a/doc/guides/architecture.rst
+++ b/doc/guides/architecture.rst
@@ -20,11 +20,11 @@ Goals
 The goal of the recommendations and suggestions in this guide are to help us
 reach a number of big picture goals.  We want Launchpad to be:
 
- * Blazingly fast
- * Always available
- * Change safely
- * Simple to make, manage and use
- * Flexible
+* Blazingly fast
+* Always available
+* Change safely
+* Simple to make, manage and use
+* Flexible
 
 However it's hard when making any particular design choice to be confident
 that it drives us towards these goals: they are quite specific, and not
@@ -48,12 +48,12 @@ easier it will be to meet our goals.
 
 The values are:
 
- * Transparency
- * Loose coupling
- * Highly cohesive
- * Testable
- * Predictable
- * Simple
+* Transparency
+* Loose coupling
+* Highly cohesive
+* Testable
+* Predictable
+* Simple
 
 Transparency
 ------------
@@ -63,19 +63,19 @@ into ``pdb`` or taking guesses.
 
 Some specific things that aid transparency:
 
- * For blocking calls (SQL, bzr, email, librarian, backend web services,
-   memcache) use ``lp.services.timeline.requesttimeline`` to record the
-   call.  This includes it in OOPS reports.
- * fine grained just-in-time logging (e.g. bzr's ``-Dhpssdetail`` option)
+* For blocking calls (SQL, bzr, email, librarian, backend web services,
+  memcache) use ``lp.services.timeline.requesttimeline`` to record the call.
+  This includes it in OOPS reports.
+* fine grained just-in-time logging (e.g. bzr's ``-Dhpssdetail`` option)
 
- * live status information 
-   * (+opstats, but more so)
-   * cron script status
-   * migration script status
+* live status information 
+  * (+opstats, but more so)
+  * cron script status
+  * migration script status
 
- * regular log files
- * OOPS reports - lovely
- * Which revisions/versions of the software & its dependencies are running
+* regular log files
+* OOPS reports - lovely
+* Which revisions/versions of the software & its dependencies are running
 
 We already have a lot of transparency.  We can use more.
 
diff --git a/doc/guides/python.rst b/doc/guides/python.rst
index 3ceb3ad..c426bd6 100644
--- a/doc/guides/python.rst
+++ b/doc/guides/python.rst
@@ -13,28 +13,28 @@ There are well-established conventions in the Python community, and in
 general we should follow these.  General Python conventions, and required
 reading:
 
- * `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_: Style Guide for
-   Python Code
- * `PEP 257 <https://www.python.org/dev/peps/pep-0257/>`_: Docstring
-   Conventions
- * The Zen of Python: ``python3 -c "import this"``
+* `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_: Style Guide for
+  Python Code
+* `PEP 257 <https://www.python.org/dev/peps/pep-0257/>`_: Docstring
+  Conventions
+* The Zen of Python: ``python3 -c "import this"``
 
 Note that our standards differ slightly from PEP-8 in some cases.
 
 Coding standards other projects use:
 
- * `Twisted Coding Standard
-   <https://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html>`_
- * `Zope developer guidelines
-   <https://www.zope.org/developer/guidelines.html>`_
+* `Twisted Coding Standard
+  <https://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html>`_
+* `Zope developer guidelines
+  <https://www.zope.org/developer/guidelines.html>`_
 
 Related Documents
 =================
 
- * `Exception guidelines <https://dev.launchpad.net/ExceptionGuidelines>`_
- * `Assertions <https://dev.launchpad.net/AssertionsInLaunchpad>`_
- * `Launchpad hacking FAQ <https://dev.launchpad.net/LaunchpadHackingFAQ>`_
- * `Tests style guide <https://dev.launchpad.net/TestsStyleGuide>`_
+* `Exception guidelines <https://dev.launchpad.net/ExceptionGuidelines>`_
+* `Assertions <https://dev.launchpad.net/AssertionsInLaunchpad>`_
+* `Launchpad hacking FAQ <https://dev.launchpad.net/LaunchpadHackingFAQ>`_
+* `Tests style guide <https://dev.launchpad.net/TestsStyleGuide>`_
 
 Whitespace and Wrapping
 =======================
@@ -42,10 +42,10 @@ Whitespace and Wrapping
 (Most of this is likely to be delegated to `black
 <https://github.com/psf/black>`_ in the near future.)
 
- * Code should fit within 78 columns, so as to fit nicely in an 80 column
-   terminal, even when quoted in an email.
- * Indents should be 4 spaces.
- * **No tabs**.  This is not negotiable.
+* Code should fit within 78 columns, so as to fit nicely in an 80 column
+  terminal, even when quoted in an email.
+* Indents should be 4 spaces.
+* **No tabs**.  This is not negotiable.
 
 .. _multiline:
 
@@ -77,11 +77,11 @@ Naming
 Consistency with existing code is the top priority.  We follow PEP-8 with
 the following exceptions:
 
- * ``CamelCase``: classes, interfaces (beginning with ``I``)
- * ``initialCamelCase``: methods
- * ``lowercase_underscores``: functions, non-method attributes, properties,
-   local variables
- * ``ALL_CAPS``: constants
+* ``CamelCase``: classes, interfaces (beginning with ``I``)
+* ``initialCamelCase``: methods
+* ``lowercase_underscores``: functions, non-method attributes, properties,
+  local variables
+* ``ALL_CAPS``: constants
 
 Private names are private
 -------------------------
@@ -93,14 +93,14 @@ anywhere outside class A.
 Docstrings
 ==========
 
- * If you haven't already, read `PEP 257
-   <https://www.python.org/dev/peps/pep-0257/>`_.
- * In general, everything that can have a docstring should: modules,
-   classes, methods, functions.
- * Docstrings should always be enclosed in triple double quotes: ``"""Like
-   this."""``
- * When a class or a method implements an interface, the docstring should
-   say ``"""See `IFoo`."""``
+* If you haven't already, read `PEP 257
+  <https://www.python.org/dev/peps/pep-0257/>`_.
+* In general, everything that can have a docstring should: modules, classes,
+  methods, functions.
+* Docstrings should always be enclosed in triple double quotes: ``"""Like
+  this."""``
+* When a class or a method implements an interface, the docstring should say
+  ``"""See `IFoo`."""``
 
 Docstrings should be valid `reStructuredText
 <https://docutils.sourceforge.io/rst.html>`_ (with all the painful
@@ -171,11 +171,11 @@ Restrictions
 
 There are restrictions on which imports can happen in Launchpad.  Namely:
 
- * View code cannot import code from ``lp.*.model``.
- * ``import *`` cannot be used if the module being imported from does not
-   have an ``__all__``.
- * Database code may not import ``zope.exceptions.NotFoundError`` -- it must
-   instead use ``lp.app.errors.NotFoundError``.
+* View code cannot import code from ``lp.*.model``.
+* ``import *`` cannot be used if the module being imported from does not
+  have an ``__all__``.
+* Database code may not import ``zope.exceptions.NotFoundError`` -- it must
+  instead use ``lp.app.errors.NotFoundError``.
 
 These restrictions are enforced by the Import Pedant, which will cause your
 tests not to pass if you don't abide by the rules.
@@ -242,16 +242,16 @@ Short of adopting something like Zope's lazy imports (which has issues of
 its own), you can't avoid this, so here are some tips to make it less
 painful.
 
- * Do the nested import in the least common case.  For example, if 5 methods
-   in ``model/mailinglist.py`` need access to ``EmailAddress`` but only one
-   method in ``model/emailaddress.py`` needs access to ``MailingList``, put
-   the import inside the ``emailaddress.py`` method, so you have fewer
-   overall nested imports.
- * Clearly comment that the nested import is for avoiding a circular import,
-   using the example below.
- * Put the nested import at the top of the method.
+* Do the nested import in the least common case.  For example, if 5 methods
+  in ``model/mailinglist.py`` need access to ``EmailAddress`` but only one
+  method in ``model/emailaddress.py`` needs access to ``MailingList``, put
+  the import inside the ``emailaddress.py`` method, so you have fewer
+  overall nested imports.
+* Clearly comment that the nested import is for avoiding a circular import,
+  using the example below.
+* Put the nested import at the top of the method.
 
-... code-block:: python
+.. code-block:: python
 
     def doFooWithBar(self, ...):
         # Import this here to avoid circular imports.