Skip to content

Commit

Permalink
Add code style info into empty documentation page
Browse files Browse the repository at this point in the history
Re: #77.
  • Loading branch information
drmfinlay committed Oct 31, 2019
1 parent 69ce05a commit 4482c64
Showing 1 changed file with 46 additions and 1 deletion.
47 changes: 46 additions & 1 deletion documentation/code_style.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,49 @@
.. _RefCodeStyle:

Code style
****************************************************************************
============================================================================

Dragonfly's code base generally follows the `PEP 8 Style Guide for Python
Code <https://legacy.python.org/dev/peps/pep-0008/>`__. There are some parts
of Dragonfly that don't follow that guide precisely, which is okay; it is
only a guideline and blind adherence to it can actually be bad sometimes
(see PEP 8 `A Foolish Consistency is the Hobgoblin of Little Minds
<https://legacy.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`__).

When making code submissions for Dragonfly, try to generally stick to the
PEP 8 style guide.

Dragonfly's source files have historically had a maximum line length of 76
characters, although up to 85 characters is fine (PEP 8). The exception to
this rule is where a long URL is used in a comment or string. Long URLs
should usually be on separate lines.


Documentation style
============================================================================

Most docstrings in Dragonfly generally follow the `Sphinx docstring format
<https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`__.
A different style is used in some places, mostly for constructor arguments::

class Grammar(object):
"""
Grammar class for managing a set of rules.

Constructor arguments:
- *name* -- name of this grammar
- *description* (str, default: None) --
description for this grammar
- *context* (Context, default: None) --
context within which to be active. If *None*, the grammar will
always be active.

"""

The Sphinx docstring format is preferred, although the above format
is also acceptable. The important thing is that the documentation is
readable in the source file and in the various generated formats
(e.g. HTML, PDF, man page).

Notice that the docstring's content is also indented. This is done in
a few places and is also acceptable.

0 comments on commit 4482c64

Please sign in to comment.