Skip to content

Commit

Permalink
MNT: Wrap long lines in docs.
Browse files Browse the repository at this point in the history 
This allows us to run doc8 cleanly.
  • Loading branch information
@dopplershift
dopplershift committed Oct 4, 2016
1 parent be4bef6 commit 3b65d33
Show file tree
Hide file tree
Showing 3 changed files with 76 additions and 64 deletions.
132 changes: 71 additions & 61 deletions docs/source/developerguide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,39 +32,42 @@ run directly out of the git repository.
Making Changes
--------------

The changes to the Siphon source (and documentation) should be made via GitHub pull requests against ``master``, even
for those with administration rights. While it's tempting to make changes directly to ``master`` and push them
up, it is better to make a pull request so that others can give feedback. If nothing else, this gives a chance
for the automated tests to run on the PR. This can eliminate "brown paper bag" moments with buggy commits on
the master branch.

During the Pull Request process, before the final merge, it's a good idea to rebase the branch and squash together
smaller commits. It's not necessary to flatten the entire branch, but it can be nice to eliminate small fixes and
get the merge down to logically arranged commit. This can also be used to hide sins from history--this is the
only chance, since once it hits ``master``, it's there forever!
The changes to the Siphon source (and documentation) should be made via GitHub pull requests
against ``master``, even for those with administration rights. While it's tempting to make
changes directly to ``master`` and push them up, it is better to make a pull request so that
others can give feedback. If nothing else, this gives a chance for the automated tests to run
on the PR. This can eliminate "brown paper bag" moments with buggy commits on the master
branch.

During the Pull Request process, before the final merge, it's a good idea to rebase the branch
and squash together smaller commits. It's not necessary to flatten the entire branch, but it
can be nice to eliminate small fixes and get the merge down to logically arranged commit. This
can also be used to hide sins from history--this is the only chance, since once it hits
``master``, it's there forever!

----------
Versioning
----------

To manage identifying the version of the code, Siphon relies upon
`versioneer <https://github.com/warner/python-versioneer>`_. ``versioneer`` takes the current
version of the source from git tags and any additional commits. For development, the version will have a string
like ``0.1.1+76.g136e37b.dirty``, which comes from ``git describe``. This version means that the current code is
76 commits past the 0.1.1 tag, on git hash ``136e37b``, with local changes on top (indicated by ``dirty``). For
a release, or non-git repo source dir, the version will just come from the most recent tag (i.e. ``v0.1.1``).
To manage identifying the version of the code, Siphon relies upon `versioneer
<https://github.com/warner/python-versioneer>`_. ``versioneer`` takes the current version of
the source from git tags and any additional commits. For development, the version will have a
string like ``0.1.1+76.g136e37b.dirty``, which comes from ``git describe``. This version means
that the current code is 76 commits past the 0.1.1 tag, on git hash ``136e37b``, with local
changes on top (indicated by ``dirty``). For a release, or non-git repo source dir, the version
will just come from the most recent tag (i.e. ``v0.1.1``).

To make a new version, simply add a new tag with a name like ``vMajor.Minor.Bugfix`` and push to GitHub. Github
will add a new release with a source archive.zip file. Running
To make a new version, simply add a new tag with a name like ``vMajor.Minor.Bugfix`` and push
to GitHub. Github will add a new release with a source archive.zip file. Running

.. parsed-literal::
python setup.py sdist
will build a new source distribution with the appropriately generated version file as well. This will also create
a new stable set of documentation.
will build a new source distribution with the appropriately generated version file as well.
This will also create a new stable set of documentation.

``versioneer`` is installed in the base of the repository. To update, install the latest copy using
``pip install versioneer``. Then recreate the ``_version.py`` file using:
``versioneer`` is installed in the base of the repository. To update, install the latest copy
using ``pip install versioneer``. Then recreate the ``_version.py`` file using:

.. parsed-literal::
python setup.py versioneer
Expand All @@ -73,9 +76,10 @@ a new stable set of documentation.
Testing
-------

Unit tests are the lifeblood of the project, as it ensures that we can continue to add and change the code
and stay confident that things have not broken. Running the tests requires ``pytest``, which is easily available
through ``conda`` or ``pip``. Running the tests can be done via either:
Unit tests are the lifeblood of the project, as it ensures that we can continue to add and
change the code and stay confident that things have not broken. Running the tests requires
``pytest``, which is easily available through ``conda`` or ``pip``. Running the tests can be
done via either:

.. parsed-literal::
python setup.py test
Expand All @@ -85,9 +89,9 @@ or
.. parsed-literal::
py.test
Using ``py.test`` also gives you the option of passing a path to the directory with tests to run, which can speed
running only the tests of interest when doing development. For instance, to only run the tests in the ``siphon/cdmr``
directory, use:
Using ``py.test`` also gives you the option of passing a path to the directory with tests to
run, which can speed running only the tests of interest when doing development. For instance,
to only run the tests in the ``siphon/cdmr`` directory, use:

.. parsed-literal::
py.test siphon/cdmr
Expand All @@ -96,15 +100,17 @@ directory, use:
Code Style
----------

Siphon uses the Python code style outlined in `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_. For better or
worse, this is what the majority of the Python world uses. The one deviation is that line length limit is 95
characters. 80 is a good target, but some times longer lines are needed.
Siphon uses the Python code style outlined in `PEP8
<https://www.python.org/dev/peps/pep-0008/>`_. For better or worse, this is what the majority
of the Python world uses. The one deviation is that line length limit is 95 characters. 80 is a
good target, but some times longer lines are needed.

While the authors are no fans of blind adherence to style and so-called project "clean-ups" that go through
and correct code style, Siphon has adopted this style from the outset. Therefore, it makes sense to enforce
this style as code is added to keep everything clean and uniform. To this end, part of the automated testing for
Siphon checks style. To check style locally within the source directory you can use the ``flake8`` tool. Running it
from the root of the source directory is as easy as:
While the authors are no fans of blind adherence to style and so-called project "clean-ups"
that go through and correct code style, Siphon has adopted this style from the outset.
Therefore, it makes sense to enforce this style as code is added to keep everything clean and
uniform. To this end, part of the automated testing for Siphon checks style. To check style
locally within the source directory you can use the ``flake8`` tool. Running it from the root
of the source directory is as easy as:

.. parsed-literal::
flake8 siphon
Expand All @@ -113,49 +119,53 @@ from the root of the source directory is as easy as:
Documentation
-------------

Siphon's documentation is built using sphinx >= 1.3. API documentation is automatically generated from
docstrings, written using the
Siphon's documentation is built using sphinx >= 1.3. API documentation is automatically
generated from docstrings, written using the
`NumPy docstring standard <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
There are also example IPython notebooks in the ``examples/notebooks`` directory. Using IPython's API,
these are automatically converted to restructured text for inclusion in the documentation. The examples can
also be converted to standalone scripts using:
There are also example IPython notebooks in the ``examples/notebooks`` directory. Using
IPython's API, these are automatically converted to restructured text for inclusion in the
documentation. The examples can also be converted to standalone scripts using:

.. parsed-literal::
python setup.py examples
The documentation is hosted by `Read the Docs <http://siphon.readthedocs.org>`_. The docs are built automatically
from ``master`` as well as for the tagged versions on github. ``master`` is used for the ``latest`` documentation,
and the latest tagged version is used for the ``stable`` documentation. To see what the docs will look like on RTD,
you also need to install the ``sphinx-rtd-theme`` package.
The documentation is hosted by `Read the Docs <http://siphon.readthedocs.org>`_. The docs are
built automatically from ``master`` as well as for the tagged versions on github. ``master`` is
used for the ``latest`` documentation, and the latest tagged version is used for the ``stable``
documentation. To see what the docs will look like on RTD, you also need to install the
``sphinx-rtd-theme`` package.

-----------
Other Tools
-----------

Continuous integration is performed by `Travis CI <http://www.travis-ci.org/Unidata/siphon>`_. This service runs the
unit tests on all support versions, as well as runs against the minimum package versions. ``flake8`` is also run
against the code to check formatting. Travis is also used to build the documentation and to run the examples to
ensure they stay working.
Continuous integration is performed by `Travis CI <http://www.travis-ci.org/Unidata/siphon>`_.
This service runs the unit tests on all support versions, as well as runs against the minimum
package versions. ``flake8`` is also run against the code to check formatting. Travis is also
used to build the documentation and to run the examples to ensure they stay working.

Test coverage is monitored by `Coveralls.io <https://coveralls.io/r/Unidata/siphon>`_.

`Landscape.io <https://landscape.io/github/Unidata/siphon>`_ is used to track code quality using the ``prospector`` tool.
`Landscape.io <https://landscape.io/github/Unidata/siphon>`_ is used to track code quality
using the ``prospector`` tool.

---------
Releasing
---------

To create a new release:

1. Go to the GitHub page and make a new release. The tag should be a sensible version number, like v1.0.0. Add a
name (can just be the version) and add some notes on what the big changes are.
2. Do a pull locally to grab the new tag. This will ensure that ``versioneer`` will give you the proper version.
3. (optional) Perform a ``git clean -f -x -d`` from the root of the repository. This will **delete** everything not
tracked by git, but will also ensure clean source distribution. ``MANIFEST.in`` is set to include/exclude mostly
correctly, but could miss some things.
1. Go to the GitHub page and make a new release. The tag should be a sensible version number,
like v1.0.0. Add a name (can just be the version) and add some notes on what the big
changes are.
2. Do a pull locally to grab the new tag. This will ensure that ``versioneer`` will give you
the proper version.
3. (optional) Perform a ``git clean -f -x -d`` from the root of the repository. This will
**delete** everything not tracked by git, but will also ensure clean source distribution.
``MANIFEST.in`` is set to include/exclude mostly correctly, but could miss some things.
4. Run ``python setup.py sdist bdist_wheel`` (this requires ``wheel`` is installed).
5. Upload using ``twine``: ``twine upload dist/*``, assuming the ``dist/`` directory contains only files for this
release. This upload process will include any changes to the ``README`` as well as any updated flags from
``setup.py``.
6. Tagging a new version on GitHub should also update the `stable <http://siphon.readthedocs.org/en/stable>`_ docs on
Read the Docs.
5. Upload using ``twine``: ``twine upload dist/*``, assuming the ``dist/`` directory contains
only files for this release. This upload process will include any changes to the ``README``
as well as any updated flags from ``setup.py``.
6. Tagging a new version on GitHub should also update the
`stable <http://siphon.readthedocs.org/en/stable>`_ docs on Read the Docs.
3 changes: 2 additions & 1 deletion docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ __ https://github.com/Unidata/siphon/issues
Other Resources
---------------

* The materials_ for Unidata's annual Python training workshop includes some tutorials on using Siphon.
* The materials_ for Unidata's annual Python training workshop includes some tutorials on
using Siphon.

.. _materials: http://github.com/Unidata/unidata-python-workshop

Expand Down
5 changes: 3 additions & 2 deletions docs/source/installguide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,9 @@ This will build and install Siphon into your current Python installation.
Examples
--------

The Siphon source comes with a set of example IPython notebooks in the ``examples/notebooks`` directory.
These can also be converted to standalone scripts (provided IPython is installed) using:
The Siphon source comes with a set of example IPython notebooks in the ``examples/notebooks``
directory. These can also be converted to standalone scripts (provided IPython is installed)
using:

.. parsed-literal::
python setup.py examples
Expand Down

0 comments on commit 3b65d33

Please sign in to comment.