From 0cca0ad7cf144697f46524a89f1839c1e375e210 Mon Sep 17 00:00:00 2001 From: Jonathan Waltman Date: Thu, 29 Nov 2012 19:11:19 -0600 Subject: [PATCH 1/3] Add initial draft of "Sphinx Developer's Guide" --- doc/contents.rst | 1 + doc/devguide.rst | 184 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 doc/devguide.rst diff --git a/doc/contents.rst b/doc/contents.rst index 3bbc28350..5e0ae6c12 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -22,6 +22,7 @@ Sphinx documentation contents faq glossary + devguide changes examples diff --git a/doc/devguide.rst b/doc/devguide.rst new file mode 100644 index 000000000..a47d7dfda --- /dev/null +++ b/doc/devguide.rst @@ -0,0 +1,184 @@ +************************** + Sphinx Developer's Guide +************************** + +.. topic:: Abstract + + This document describes the development process of Sphinx, a documentation + system used by developers to document systems used by other developers to + develop other systems that may also be documented using Sphinx. + +The Sphinx source code is managed using `Mercurial`_ and is hosted on +`BitBucket`_. + + hg clone https://bitbucket.org/birkenfeld/sphinx + +.. rubric:: Community + +sphinx-users + Mailing list for user support. + +sphinx-dev + Mailing list for development related discussions. + +#pocoo on irc.freenode.net + IRC channel for development questions and user support. + + This channel is shared with other Pocoo projects. Archived logs are + available `here `_. + +.. _`BitBucket`: http://bitbucket.org +.. _`Mercurial`: http://mercurial.selenic.com/ + + +Bug Reports and Feature Requests +-------------------------------- + +If you have encountered a problem with Sphinx or have an idea for a new +feature, please submit it to the `issue tracker`_ on BitBucket or discuss it +on the sphinx-dev mailing list. + +For bug reports, please include the output produced during the build process +and also the log file Sphinx creates after it encounters an un-handled +exception. The location of this file should be shown towards the end of the +error message. + +Including or providing a link to the source files involved may help us fix the +issue. If possible, try to create a minimal project that produces the error +and post that instead. + +.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues + + +Contributing to Sphinx +---------------------- + +The recommended way to contribute code to Sphinx is to fork the Mercurial +repository on BitBucket and then submit a pull request after committing your +changes. + +These are the basic steps needed to start developing. + +.. todo:: + + Recommend using named branches? + + +#. Create an account on BitBucket. + +#. Fork the main Sphinx repository (`birkenfeld/sphinx + `_) using the BitBucket interface. + +#. Clone the forked repository to your machine. :: + + hg clone https://bitbucket.org/USERNAME/sphinx-fork + cd sphinx-fork + +#. Checkout the appropriate branch. + + For changes that should be included in the next minor release (namely bug + fixes), use the ``stable`` branch. :: + + hg checkout stable + + For new features or other substantial changes that should wait until the + next major release, use the ``default`` branch. + +#. Setup your Python environment. :: + + virtualenv ~/sphinxenv + . ~/sphinxenv/bin/activate + pip install -e . + +#. Hack, hack, hack. + + For tips on working with the code, see the `Coding Guide`_. + +#. Test, test, test. + + Run the unit tests:: + + pip install nose + make test + + Build the documentation and check the output for different builders:: + + cd docs + make clean html text man info latexpdf + + Run the unit tests under different Python environments using + :program:`tox`:: + + pip install tox + tox -v + + Add a new unit test in the ``tests`` directory if you can. + + For bug fixes, first add a test that fails without your changes and passes + after they are applied. + +#. Commit your changes. :: + + hg commit -m 'Add useful new feature that does this.' + + BitBucket recognizes `certain phrases`__ that can be used to automatically + update the issue tracker. + + For example:: + + hg commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' + + would close issue #42. + + __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code + +#. Push changes to your forked repo on BitBucket. :: + + hg push + +#. Submit a pull request from your repo to ``birkenfeld/sphinx`` using the + BitBucket interface. + + +Coding Guide +------------ + +* Try to use the same code style as used in the rest of the project. See the + `Pocoo Styleguide`__ for more information. + + __ http://flask.pocoo.org/docs/styleguide/ + +* For non-trivial changes, please update the :file:`CHANGES` file. If your + changes alter existing behavior, please document this. + +* New features should be documented. Include examples and use cases where + appropriate. If possible, include a sample that is displayed in the + generated output. + +* When adding a new configuration variable, be sure to document it and update + :file:`sphinx/quickstart.py`. + +* Use the included :program:`utils/check_sources.py` script to check for + common formatting issues (trailing whitespace, lengthy lines, etc). + + +Debugging Tips +~~~~~~~~~~~~~~ + +* Delete the build cache before building documents if you make changes in the + code by running the command ``make clean`` or using the + :option:`sphinx-build -E` option. + +* Use the :option:`sphinx-build -P` option to run Pdb on exceptions. + +* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable + representation of the document structure. + +* Set the configuration variable :confval:`keep_warnings` to True so warnings + will be displayed in the generated output. + +* Set the configuration variable :confval:`nitpicky` to True so that Sphinx + will complain about references without a known target. + +* Set the debugging options in the `Docutils configuration file + `_. From 196cb44c30f7ef21d55df252f059414efc32699e Mon Sep 17 00:00:00 2001 From: Jonathan Waltman Date: Sun, 2 Dec 2012 01:18:54 -0600 Subject: [PATCH 2/3] devguide: Elaborate on pull requests --- doc/devguide.rst | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/doc/devguide.rst b/doc/devguide.rst index a47d7dfda..e175a6f47 100644 --- a/doc/devguide.rst +++ b/doc/devguide.rst @@ -1,6 +1,5 @@ -************************** - Sphinx Developer's Guide -************************** +Sphinx Developer's Guide +======================== .. topic:: Abstract @@ -18,7 +17,7 @@ The Sphinx source code is managed using `Mercurial`_ and is hosted on sphinx-users Mailing list for user support. -sphinx-dev +sphinx-dev Mailing list for development related discussions. #pocoo on irc.freenode.net @@ -53,11 +52,19 @@ and post that instead. Contributing to Sphinx ---------------------- -The recommended way to contribute code to Sphinx is to fork the Mercurial -repository on BitBucket and then submit a pull request after committing your -changes. +The recommended way for new contributors to submit code to Sphinx is to fork +the Mercurial repository on BitBucket and then submit a pull request after +committing the changes. -These are the basic steps needed to start developing. +Developers with write access to the main repository are also encouraged to +create pull requests for non-trivial changes so they may be reviewed before +being committed. + + +Getting Started +~~~~~~~~~~~~~~~ + +These are the basic steps needed to start developing on Sphinx. .. todo:: @@ -132,12 +139,15 @@ These are the basic steps needed to start developing. __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code -#. Push changes to your forked repo on BitBucket. :: +#. Push changes to your forked repository on BitBucket. :: hg push -#. Submit a pull request from your repo to ``birkenfeld/sphinx`` using the - BitBucket interface. +#. Submit a pull request from your repository to ``birkenfeld/sphinx`` using + the BitBucket interface. + + The pull request will be reviewed and if approved, merged by one of the + Sphinx developers. Coding Guide From 3a8673a66b6451a9e9bab3e6647c39b6044faffb Mon Sep 17 00:00:00 2001 From: Jonathan Waltman Date: Mon, 3 Dec 2012 00:55:47 -0600 Subject: [PATCH 3/3] devguide: Add guidelines for core developers --- doc/devguide.rst | 44 ++++++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/doc/devguide.rst b/doc/devguide.rst index e175a6f47..ab4bc7409 100644 --- a/doc/devguide.rst +++ b/doc/devguide.rst @@ -54,11 +54,8 @@ Contributing to Sphinx The recommended way for new contributors to submit code to Sphinx is to fork the Mercurial repository on BitBucket and then submit a pull request after -committing the changes. - -Developers with write access to the main repository are also encouraged to -create pull requests for non-trivial changes so they may be reviewed before -being committed. +committing the changes. The pull request will then need to be approved by one +of the core developers before it is merged into the main repository. Getting Started @@ -66,11 +63,6 @@ Getting Started These are the basic steps needed to start developing on Sphinx. -.. todo:: - - Recommend using named branches? - - #. Create an account on BitBucket. #. Fork the main Sphinx repository (`birkenfeld/sphinx @@ -146,8 +138,34 @@ These are the basic steps needed to start developing on Sphinx. #. Submit a pull request from your repository to ``birkenfeld/sphinx`` using the BitBucket interface. - The pull request will be reviewed and if approved, merged by one of the - Sphinx developers. +#. Wait for a core developer to review your changes. + + +Core Developers +~~~~~~~~~~~~~~~ + +The core developers of Sphinx have write access to the main repository. They +can commit changes, accept/reject pull requests, and manage items on the issue +tracker. + +You do not need to be a core developer or have write access to be involved in +the development of Sphinx. You can submit patches or create pull requests +from forked repositories and have a core developer add the changes for you. + +The following are some general guidelines for core developers: + +* Questionable or extensive changes should be submitted as a pull request + instead of being committed directly to the main repository. The pull + request should be reviewed by another core developer before it is merged. + +* Trivial changes can be committed directly but be sure to keep the repository + in a good working state and that all tests pass before pushing your changes. + +* When committing code written by someone else, please attribute the original + author in the commit message and any relevant :file:`CHANGES` entry. + +* Using Mercurial named branches other than ``default`` and ``stable`` is not + encouraged. Coding Guide @@ -171,6 +189,8 @@ Coding Guide * Use the included :program:`utils/check_sources.py` script to check for common formatting issues (trailing whitespace, lengthy lines, etc). +* Add appropriate unit tests. + Debugging Tips ~~~~~~~~~~~~~~