diff --git a/CHANGES b/CHANGES index 110a8d184..921c099c3 100644 --- a/CHANGES +++ b/CHANGES @@ -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 -`__. +in the source distribution or `at Github +`__. diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 4a350ae47..1a207bb5c 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -7,7 +7,7 @@

{%trans%}This documentation is for version {{ version }}, which is not released yet.{%endtrans%}

{%trans%}You can use it from the - Mercurial repo or look for + Git repo or look for released versions in the Python Package Index.{%endtrans%}

{% else %} @@ -30,4 +30,4 @@ are also available.{%endtrans%}

{%trans%}or come to the #sphinx-doc channel on FreeNode.{%endtrans%}

{%trans%}You can also open an issue at the - tracker.{%endtrans%}

+ tracker.{%endtrans%}

diff --git a/doc/develop.rst b/doc/develop.rst index aad3ff1ef..756c8c44b 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -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 - `_. + `_. * The mailing list for development is at `Google Groups `_. * There is also the #sphinx-doc IRC channel on `freenode diff --git a/doc/devguide.rst b/doc/devguide.rst index fccdd3fa7..04ef5b2a6 100644 --- a/doc/devguide.rst +++ b/doc/devguide.rst @@ -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-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 - `_) using the BitBucket interface. +#. Fork the main Sphinx repository (`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 -`_. 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 +`_. 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 `_. + +* JavaScript stemming algorithms in `sphinx/search/*.py` (except `en.py`) are + generated by this + `modified snowballcode generator `_. + Generated `JSX `_ files are + in `this repository `_. + You can get the resulting JavaScript files using the following command: + + .. code-block:: bash + + $ npm install + $ node_modules/.bin/grunt build # -> dest/*.global.js diff --git a/doc/ext/extlinks.rst b/doc/ext/extlinks.rst index d8bcaa524..90324cc1c 100644 --- a/doc/ext/extlinks.rst +++ b/doc/ext/extlinks.rst @@ -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``. diff --git a/doc/extensions.rst b/doc/extensions.rst index b2adbc1a8..1c297f55c 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -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 `__ 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 `_). -.. _Wiki at BitBucket: https://bitbucket.org/birkenfeld/sphinx/wiki/Home .. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib diff --git a/doc/install.rst b/doc/install.rst index bf6538722..323cf4299 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -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 `_. -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 `_ +* as a `.tar.bz2 `_ file or -* as a `.zip `_ file +* as a `.zip `_ file There are introductions for several environments: diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index ec24d9026..69817e444 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -292,5 +292,5 @@ def main(argv): 'can be provided next time.') print >>error, ( 'A bug report can be filed in the tracker at ' - '. Thanks!') + '. Thanks!') return 1 diff --git a/utils/release-checklist b/utils/release-checklist index ab234f3ea..6a8e4c0fd 100644 --- a/utils/release-checklist +++ b/utils/release-checklist @@ -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