IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

development process updates: bb->gh, hg->git

Browse Source
This commit is contained in:
Georg Brandl 2015-01-02 13:49:38 +01:00
parent 10db0188af
commit a84e036622
9 changed files with 87 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGES
View File

@ -1220,5 +1220,5 @@ Previous versions
================= =================
The changelog for versions before 1.0 can be found in the file ``CHANGES.old`` The changelog for versions before 1.0 can be found in the file ``CHANGES.old``
in the source distribution or `at BitBucket in the source distribution or `at Github
<https://bitbucket.org/birkenfeld/sphinx/raw/tip/CHANGES.old>`__. <https://github.com/sphinx-doc/sphinx/raw/master/CHANGES.old>`__.

4
doc/_templates/indexsidebar.html vendored
View File

@ -7,7 +7,7 @@
<p>{%trans%}This documentation is for version <b>{{ version }}</b>, which is <p>{%trans%}This documentation is for version <b>{{ version }}</b>, which is
not released yet.{%endtrans%}</p> not released yet.{%endtrans%}</p>
<p>{%trans%}You can use it from the <p>{%trans%}You can use it from the
<a href="http://bitbucket.org/birkenfeld/sphinx/">Mercurial repo</a> or look for <a href="https://github.com/sphinx-doc/sphinx/">Git repo</a> or look for
released versions in the <a href="http://pypi.python.org/pypi/Sphinx">Python released versions in the <a href="http://pypi.python.org/pypi/Sphinx">Python
Package Index</a>.{%endtrans%}</p> Package Index</a>.{%endtrans%}</p>
{% else %} {% else %}
@ -30,4 +30,4 @@ are also available.{%endtrans%}</p>
</form> </form>
<p>{%trans%}or come to the <tt>#sphinx-doc</tt> channel on FreeNode.{%endtrans%}</p> <p>{%trans%}or come to the <tt>#sphinx-doc</tt> channel on FreeNode.{%endtrans%}</p>
<p>{%trans%}You can also open an issue at the <p>{%trans%}You can also open an issue at the
<a href="http://www.bitbucket.org/birkenfeld/sphinx/issues/">tracker</a>.{%endtrans%}</p> <a href="https://github.com/sphinx-doc/sphinx/issues">tracker</a>.{%endtrans%}</p>

6
doc/develop.rst
View File

@ -5,10 +5,10 @@ Sphinx development
Sphinx is a maintained by a group of volunteers. We value every contribution! Sphinx is a maintained by a group of volunteers. We value every contribution!
* The code can be found in a Mercurial repository, at * The code can be found in a Git repository, at
https://bitbucket.org/birkenfeld/sphinx/. https://github.com/sphinx-doc/sphinx/.
* Issues and feature requests should be raised in the `tracker * Issues and feature requests should be raised in the `tracker
<https://bitbucket.org/birkenfeld/sphinx/issues/>`_. <https://github.com/sphinx-doc/sphinx/issues>`_.
* The mailing list for development is at `Google Groups * The mailing list for development is at `Google Groups
<https://groups.google.com/group/sphinx-dev/>`_. <https://groups.google.com/group/sphinx-dev/>`_.
* There is also the #sphinx-doc IRC channel on `freenode * There is also the #sphinx-doc IRC channel on `freenode

101
doc/devguide.rst
View File

@ -7,10 +7,9 @@ Sphinx Developer's Guide
system used by developers to document systems used by other developers to system used by developers to document systems used by other developers to
develop other systems that may also be documented using Sphinx. develop other systems that may also be documented using Sphinx.
The Sphinx source code is managed using `Mercurial`_ and is hosted on The Sphinx source code is managed using Git and is hosted on Github.
`BitBucket`_.
hg clone https://bitbucket.org/birkenfeld/sphinx git clone git://github.com/sphinx-doc/sphinx
.. rubric:: Community .. rubric:: Community
@ -23,15 +22,12 @@ sphinx-dev <sphinx-dev@googlegroups.com>
#sphinx-doc on irc.freenode.net #sphinx-doc on irc.freenode.net
IRC channel for development questions and user support. IRC channel for development questions and user support.
.. _`BitBucket`: https://bitbucket.org/
.. _`Mercurial`: http://mercurial.selenic.com/
Bug Reports and Feature Requests Bug Reports and Feature Requests
-------------------------------- --------------------------------
If you have encountered a problem with Sphinx or have an idea for a new 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 feature, please submit it to the `issue tracker`_ on Github or discuss it
on the sphinx-dev mailing list. on the sphinx-dev mailing list.
For bug reports, please include the output produced during the build process For bug reports, please include the output produced during the build process
@ -43,42 +39,59 @@ 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 issue. If possible, try to create a minimal project that produces the error
and post that instead. and post that instead.
.. _`issue tracker`: https://bitbucket.org/birkenfeld/sphinx/issues .. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues
Contributing to Sphinx Contributing to Sphinx
---------------------- ----------------------
The recommended way for new contributors to submit code to Sphinx is to fork 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 the repository on Github and then submit a pull request after
committing the changes. The pull request will then need to be approved by one 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. of the core developers before it is merged into the main repository.
#. Check for open issues or open a fresh issue to start a discussion around a
feature idea or a bug.
#. If you feel uncomfortable or uncertain about an issue or your changes, feel
free to email sphinx-dev@googlegroups.com.
#. Fork `the repository`_ on Github to start making your changes to the
**default** branch for next major version, or **stable** branch for next
minor version.
#. Write a test which shows that the bug was fixed or that the feature works
as expected.
#. Send a pull request and bug the maintainer until it gets merged and
published. Make sure to add yourself to AUTHORS_ and the change to
CHANGES_.
.. _`the repository`: https://github.com/sphinx-doc/sphinx
.. _AUTHORS: https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS
.. _CHANGES: https://github.com/sphinx-doc/sphinx/blob/master/CHANGES
Getting Started Getting Started
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
These are the basic steps needed to start developing on Sphinx. These are the basic steps needed to start developing on Sphinx.
#. Create an account on BitBucket. #. Create an account on Github.
#. Fork the main Sphinx repository (`birkenfeld/sphinx #. Fork the main Sphinx repository (`sphinx-doc/sphinx
<https://bitbucket.org/birkenfeld/sphinx>`_) using the BitBucket interface. <https://github.com/sphinx-doc/sphinx>`_) using the Github interface.
#. Clone the forked repository to your machine. :: #. Clone the forked repository to your machine. ::
hg clone https://bitbucket.org/USERNAME/sphinx-fork git clone https://github.com/USERNAME/sphinx
cd sphinx-fork cd sphinx
#. Checkout the appropriate branch. #. Checkout the appropriate branch.
For changes that should be included in the next minor release (namely bug For changes that should be included in the next minor release (namely bug
fixes), use the ``stable`` branch. :: fixes), use the ``stable`` branch. ::
hg checkout stable git checkout stable
For new features or other substantial changes that should wait until the For new features or other substantial changes that should wait until the
next major release, use the ``default`` branch. next major release, use the ``master`` branch.
#. Optional: setup a virtual environment. :: #. Optional: setup a virtual environment. ::
@ -86,6 +99,10 @@ These are the basic steps needed to start developing on Sphinx.
. ~/sphinxenv/bin/activate . ~/sphinxenv/bin/activate
pip install -e . pip install -e .
#. Create a new working branch. Choose any name you like. ::
git checkout -b feature-xyz
#. Hack, hack, hack. #. Hack, hack, hack.
For tips on working with the code, see the `Coding Guide`_. For tips on working with the code, see the `Coding Guide`_.
@ -113,28 +130,31 @@ These are the basic steps needed to start developing on Sphinx.
* For bug fixes, first add a test that fails without your changes and passes * For bug fixes, first add a test that fails without your changes and passes
after they are applied. after they are applied.
#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not trivial * Tests that need a sphinx-build run should be integrated in one of the
(small doc updates, typo fixes). Then commit:: existing test modules if possible. New tests that to ``@with_app`` and
then ``build_all`` for a few assertions are not good since *the test suite
should not take more than a minute to run*.
hg commit -m '#42: Add useful new feature that does this.' #. Please add a bullet point to :file:`CHANGES` if the fix or feature is not
trivial (small doc updates, typo fixes). Then commit::
BitBucket recognizes `certain phrases`__ that can be used to automatically git commit -m '#42: Add useful new feature that does this.'
Github recognizes certain phrases that can be used to automatically
update the issue tracker. update the issue tracker.
For example:: For example::
hg commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
would close issue #42. would close issue #42.
__ https://confluence.atlassian.com/display/BITBUCKET/Resolve+issues+automatically+when+users+push+code #. Push changes in the branch to your forked repository on Github. ::
#. Push changes to your forked repository on BitBucket. :: git push origin feature-xyz
hg push #. Submit a pull request from your branch to the respective branch (``master``
or ``stable``) on ``sphinx-doc/sphinx`` using the Github interface.
#. Submit a pull request from your repository to ``birkenfeld/sphinx`` using
the BitBucket interface.
#. Wait for a core developer to review your changes. #. Wait for a core developer to review your changes.
@ -162,9 +182,6 @@ The following are some general guidelines for core developers:
* When committing code written by someone else, please attribute the original * When committing code written by someone else, please attribute the original
author in the commit message and any relevant :file:`CHANGES` entry. author in the commit message and any relevant :file:`CHANGES` entry.
* Using Mercurial named branches other than ``default`` and ``stable`` is not
encouraged.
Locale updates Locale updates
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
@ -191,9 +208,9 @@ identifier and put ``sphinx.po`` in there. Don't forget to update the possible
values for :confval:`language` in ``doc/config.rst``. values for :confval:`language` in ``doc/config.rst``.
The Sphinx core messages can also be translated on `Transifex The Sphinx core messages can also be translated on `Transifex
<https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the Python <https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the
package "transifex_client", which can be used to pull translations in ``.po`` Python package "transifex_client", which can be used to pull translations in
format from Transifex. To do this, go to ``sphinx/locale`` and then run ``.po`` format from Transifex. To do this, go to ``sphinx/locale`` and then run
``tx pull -f -l LANG`` where LANG is an existing language identifier. It is ``tx pull -f -l LANG`` where LANG is an existing language identifier. It is
good practice to run ``python setup.py update_catalog`` afterwards to make sure good practice to run ``python setup.py update_catalog`` afterwards to make sure
the ``.po`` file has the canonical Babel formatting. the ``.po`` file has the canonical Babel formatting.
@ -235,11 +252,23 @@ Debugging Tips
* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable * Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable
representation of the document structure. representation of the document structure.
* Set the configuration variable :confval:`keep_warnings` to True so warnings * Set the configuration variable :confval:`keep_warnings` to ``True`` so
will be displayed in the generated output. warnings will be displayed in the generated output.
* Set the configuration variable :confval:`nitpicky` to True so that Sphinx * Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx
will complain about references without a known target. will complain about references without a known target.
* Set the debugging options in the `Docutils configuration file * Set the debugging options in the `Docutils configuration file
<http://docutils.sourceforge.net/docs/user/config.html>`_. <http://docutils.sourceforge.net/docs/user/config.html>`_.
* JavaScript stemming algorithms in `sphinx/search/*.py` (except `en.py`) are
generated by this
`modified snowballcode generator <https://github.com/shibukawa/snowball>`_.
Generated `JSX <http://jsx.github.io/>`_ files are
in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_.
You can get the resulting JavaScript files using the following command:
.. code-block:: bash
$ npm install
$ node_modules/.bin/grunt build # -> dest/*.global.js

6
doc/ext/extlinks.rst
View File

@ -15,7 +15,7 @@ so by providing aliases to base URLs, so that you only need to give the subpage
name when creating a link. name when creating a link.
Let's assume that you want to include many links to issues at the Sphinx Let's assume that you want to include many links to issues at the Sphinx
tracker, at :samp:`http://bitbucket.org/birkenfeld/sphinx/issue/{num}`. Typing tracker, at :samp:`http://github.com/sphinx-doc/sphinx/issues/{num}`. Typing
this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks` this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks`
to avoid repeating yourself. to avoid repeating yourself.
@ -27,11 +27,11 @@ The extension adds one new config value:
short alias names to a base URL and a *prefix*. For example, to create an short alias names to a base URL and a *prefix*. For example, to create an
alias for the above mentioned issues, you would add :: alias for the above mentioned issues, you would add ::
extlinks = {'issue': ('https://bitbucket.org/birkenfeld/sphinx/issue/%s', extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
'issue ')} 'issue ')}
Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This
then inserts a link to https://bitbucket.org/birkenfeld/sphinx/issue/123. then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123.
As you can see, the target given in the role is substituted in the base URL As you can see, the target given in the role is substituted in the base URL
in the place of ``%s``. in the place of ``%s``.

6
doc/extensions.rst
View File

@ -41,14 +41,14 @@ You can find several extensions contributed by users in the `Sphinx Contrib`_
repository. It is open for anyone who wants to maintain an extension repository. It is open for anyone who wants to maintain an extension
publicly; just send a short message asking for write permissions. publicly; just send a short message asking for write permissions.
There are also several extensions hosted elsewhere. The `Wiki at BitBucket`_ There are also several extensions hosted elsewhere. The `Sphinx extension
maintains a list of those. survey <http://sphinxext-survey.readthedocs.org/en/latest/>`__ contains a
comprehensive list.
If you write an extension that you think others will find useful or you think If you write an extension that you think others will find useful or you think
should be included as a part of Sphinx, please write to the project mailing should be included as a part of Sphinx, please write to the project mailing
list (`join here <https://groups.google.com/group/sphinx-dev>`_). list (`join here <https://groups.google.com/group/sphinx-dev>`_).
.. _Wiki at BitBucket: https://bitbucket.org/birkenfeld/sphinx/wiki/Home
.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib .. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib

6
doc/install.rst
View File

@ -9,11 +9,11 @@ Since Sphinx is written in the Python language, you need to install Python
Sphinx packages are available on the `Python Package Index Sphinx packages are available on the `Python Package Index
<https://pypi.python.org/pypi/Sphinx>`_. <https://pypi.python.org/pypi/Sphinx>`_.
You can also download a snapshot from the Mercurial development repository: You can also download a snapshot from the Git repository:
* as a `.tar.bz2 <https://bitbucket.org/birkenfeld/sphinx/get/default.tar.bz2>`_ * as a `.tar.bz2 <https://github.com/sphinx-doc/sphinx/archive/master.tar.bz2>`_
file or file or
* as a `.zip <https://bitbucket.org/birkenfeld/sphinx/get/default.zip>`_ file * as a `.zip <https://github.com/sphinx-doc/sphinx/archive/master.zip>`_ file
There are introductions for several environments: There are introductions for several environments:

2
sphinx/cmdline.py
View File

@ -292,5 +292,5 @@ def main(argv):
'can be provided next time.') 'can be provided next time.')
print >>error, ( print >>error, (
'A bug report can be filed in the tracker at ' 'A bug report can be filed in the tracker at '
'<https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!') '<https://github.com/sphinx-doc/sphinx/issues>. Thanks!')
return 1 return 1

10
utils/release-checklist
View File

@ -1,21 +1,21 @@
Release checklist Release checklist
================= =================
* Check hg status * Check git status
* Make check * Make check
* Update version info in sphinx/__init__.py * Update version info in sphinx/__init__.py
* Update release date in CHANGES * Update release date in CHANGES
* hg commit * git commit
* make clean * make clean
* python setup.py release bdist_wheel sdist upload * python setup.py release bdist_wheel sdist upload
* For all other versions: pythonX.Y setup.py release bdist_wheel upload * For all other versions: pythonX.Y setup.py release bdist_wheel upload
(remove build/ before each one) (remove build/ before each one)
* Check PyPI release page for obvious errors * Check PyPI release page for obvious errors
* hg tag * git tag
* Merge default into stable if final major release * Merge default into stable if final major release
* Update homepage (release info), regenerate docs (+printable!) * Update homepage (release info), regenerate docs (+printable!)
* Add new version/milestone to tracker categories * Add new version/milestone to tracker categories
* Write announcement and send to mailing list/python-announce * Write announcement and send to mailing list/python-announce
* Update version info, add new CHANGES entry for next version * Update version info, add new CHANGES entry for next version
* hg commit * git commit
* hg push * git push