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``
in the source distribution or `at BitBucket
<https://bitbucket.org/birkenfeld/sphinx/raw/tip/CHANGES.old>`__.
in the source distribution or `at Github
<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
not released yet.{%endtrans%}</p>
<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
Package Index</a>.{%endtrans%}</p>
{% else %}
@ -30,4 +30,4 @@ are also available.{%endtrans%}</p>
</form>
<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
<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!
* The code can be found in a Mercurial repository, at
https://bitbucket.org/birkenfeld/sphinx/.
* The code can be found in a Git repository, at
https://github.com/sphinx-doc/sphinx/.
* 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
<https://groups.google.com/group/sphinx-dev/>`_.
* 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
develop other systems that may also be documented using Sphinx.
The Sphinx source code is managed using `Mercurial`_ and is hosted on
`BitBucket`_.
The Sphinx source code is managed using Git and is hosted on Github.
hg clone https://bitbucket.org/birkenfeld/sphinx
git clone git://github.com/sphinx-doc/sphinx
.. rubric:: Community
@ -23,15 +22,12 @@ sphinx-dev <sphinx-dev@googlegroups.com>
#sphinx-doc on irc.freenode.net
IRC channel for development questions and user support.
.. _`BitBucket`: https://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
feature, please submit it to the `issue tracker`_ on Github or discuss it
on the sphinx-dev mailing list.
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
and post that instead.
.. _`issue tracker`: https://bitbucket.org/birkenfeld/sphinx/issues
.. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues
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
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
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
~~~~~~~~~~~~~~~
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
<https://bitbucket.org/birkenfeld/sphinx>`_) using the BitBucket interface.
#. Fork the main Sphinx repository (`sphinx-doc/sphinx
<https://github.com/sphinx-doc/sphinx>`_) using the Github interface.
#. Clone the forked repository to your machine. ::
hg clone https://bitbucket.org/USERNAME/sphinx-fork
cd sphinx-fork
git clone https://github.com/USERNAME/sphinx
cd sphinx
#. 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
git checkout stable
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. ::
@ -86,6 +99,10 @@ These are the basic steps needed to start developing on Sphinx.
. ~/sphinxenv/bin/activate
pip install -e .
#. Create a new working branch. Choose any name you like. ::
git checkout -b feature-xyz
#. Hack, hack, hack.
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
after they are applied.
#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not trivial
(small doc updates, typo fixes). Then commit::
* Tests that need a sphinx-build run should be integrated in one of the
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.
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.
__ 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 repository to ``birkenfeld/sphinx`` using
the BitBucket interface.
#. Submit a pull request from your branch to the respective branch (``master``
or ``stable``) on ``sphinx-doc/sphinx`` using the Github interface.
#. 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
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
~~~~~~~~~~~~~~
@ -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``.
The Sphinx core messages can also be translated on `Transifex
<https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the Python
package "transifex_client", which can be used to pull translations in ``.po``
format from Transifex. To do this, go to ``sphinx/locale`` and then run
<https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the
Python package "transifex_client", which can be used to pull translations in
``.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
good practice to run ``python setup.py update_catalog`` afterwards to make sure
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
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:`keep_warnings` to ``True`` so
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.
* Set the debugging options in the `Docutils configuration file
<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.
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`
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
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 ')}
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
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
publicly; just send a short message asking for write permissions.
There are also several extensions hosted elsewhere. The `Wiki at BitBucket`_
maintains a list of those.
There are also several extensions hosted elsewhere. The `Sphinx extension
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
should be included as a part of Sphinx, please write to the project mailing
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

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
<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
* 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:

2
sphinx/cmdline.py
View File

@ -292,5 +292,5 @@ def main(argv):
'can be provided next time.')
print >>error, (
'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

10
utils/release-checklist
View File

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