mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge branch 'stable'
This commit is contained in:
commit
ab00f5fe49
5
CHANGES
5
CHANGES
@ -31,10 +31,15 @@ Features added
|
||||
--------------
|
||||
|
||||
* #3241: emit latex warning if buggy titlesec (ref #3210)
|
||||
* #3194: Refer the $MAKE environment variable to determine ``make`` command
|
||||
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* #3246: xapian search adapter crashes
|
||||
* #3253: In Py2 environment, building another locale with a non-captioned
|
||||
toctree produces `None` captions
|
||||
|
||||
Release 1.5.1 (released Dec 13, 2016)
|
||||
=====================================
|
||||
|
||||
|
331
CONTRIBUTING.rst
Normal file
331
CONTRIBUTING.rst
Normal file
@ -0,0 +1,331 @@
|
||||
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 Git and is hosted on Github.
|
||||
|
||||
git clone git://github.com/sphinx-doc/sphinx
|
||||
|
||||
.. rubric:: Community
|
||||
|
||||
sphinx-users <sphinx-users@googlegroups.com>
|
||||
Mailing list for user support.
|
||||
|
||||
sphinx-dev <sphinx-dev@googlegroups.com>
|
||||
Mailing list for development related discussions.
|
||||
|
||||
#sphinx-doc on irc.freenode.net
|
||||
IRC channel for development questions and user support.
|
||||
|
||||
|
||||
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 Github 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`: 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 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
|
||||
**master** 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 Github.
|
||||
|
||||
#. 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. ::
|
||||
|
||||
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. ::
|
||||
|
||||
git checkout stable
|
||||
|
||||
For new features or other substantial changes that should wait until the
|
||||
next major release, use the ``master`` branch.
|
||||
|
||||
#. Optional: setup a virtual environment. ::
|
||||
|
||||
virtualenv ~/sphinxenv
|
||||
. ~/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`_.
|
||||
|
||||
#. Test, test, test. Possible steps:
|
||||
|
||||
* Run the unit tests::
|
||||
|
||||
pip install -r test-reqs.txt
|
||||
make test
|
||||
|
||||
* Again, it's useful to turn on deprecation warnings on so they're shown in
|
||||
the test output::
|
||||
|
||||
PYTHONWARNINGS=all make test
|
||||
|
||||
* Build the documentation and check the output for different builders::
|
||||
|
||||
cd doc
|
||||
make clean html 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.
|
||||
|
||||
* 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*.
|
||||
|
||||
#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not
|
||||
trivial (small doc updates, typo fixes). Then commit::
|
||||
|
||||
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::
|
||||
|
||||
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
|
||||
|
||||
would close issue #42.
|
||||
|
||||
#. Push changes in the branch to your forked repository on Github. ::
|
||||
|
||||
git push origin feature-xyz
|
||||
|
||||
#. 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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Locale updates
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The parts of messages in Sphinx that go into builds are translated into several
|
||||
locales. The translations are kept as gettext ``.po`` files translated from the
|
||||
master template ``sphinx/locale/sphinx.pot``.
|
||||
|
||||
Sphinx uses `Babel <http://babel.edgewall.org>`_ to extract messages and
|
||||
maintain the catalog files. It is integrated in ``setup.py``:
|
||||
|
||||
* Use ``python setup.py extract_messages`` to update the ``.pot`` template.
|
||||
* Use ``python setup.py update_catalog`` to update all existing language
|
||||
catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the
|
||||
template file.
|
||||
* Use ``python setup.py compile_catalog`` to compile the ``.po`` files to binary
|
||||
``.mo`` files and ``.js`` files.
|
||||
|
||||
When an updated ``.po`` file is submitted, run compile_catalog to commit both
|
||||
the source and the compiled catalogs.
|
||||
|
||||
When a new locale is submitted, add a new directory with the ISO 639-1 language
|
||||
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
|
||||
``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.
|
||||
|
||||
|
||||
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` if it's important enough.
|
||||
|
||||
* 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
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
* 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
|
||||
<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
|
||||
|
||||
Deprecating a feature
|
||||
---------------------
|
||||
|
||||
There are a couple reasons that code in Sphinx might be deprecated:
|
||||
|
||||
* If a feature has been improved or modified in a backwards-incompatible way,
|
||||
the old feature or behavior will be deprecated.
|
||||
|
||||
* Sometimes Sphinx will include a backport of a Python library that's not
|
||||
included in a version of Python that Sphinx currently supports. When Sphinx
|
||||
no longer needs to support the older version of Python that doesn't include
|
||||
the library, the library will be deprecated in Sphinx.
|
||||
|
||||
As the :ref:`deprecation-policy` describes,
|
||||
the first release of Sphinx that deprecates a feature (``A.B``) should raise a
|
||||
``RemovedInSphinxXXWarning`` (where XX is the Sphinx version where the feature
|
||||
will be removed) when the deprecated feature is invoked. Assuming we have good
|
||||
test coverage, these warnings are converted to errors when running the test
|
||||
suite with warnings enabled: ``python -Wall tests/run.py``. Thus, when adding
|
||||
a ``RemovedInSphinxXXWarning`` you need to eliminate or silence any warnings
|
||||
generated when running the tests.
|
||||
|
||||
.. _deprecation-policy:
|
||||
|
||||
Deprecation policy
|
||||
------------------
|
||||
|
||||
A feature release may deprecate certain features from previous releases. If a
|
||||
feature is deprecated in feature release 1.A, it will continue to work in all
|
||||
1.A.x versions (for all versions of x) but raise warnings. Deprecated features
|
||||
will be removed in the first 1.B release, or 1.B.1 for features deprecated in
|
||||
the last 1.A.x feature release to ensure deprecations are done over at least 2
|
||||
feature releases.
|
||||
|
||||
So, for example, if we decided to start the deprecation of a function in
|
||||
Sphinx 1.4:
|
||||
|
||||
* Sphinx 1.4.x will contain a backwards-compatible replica of the function
|
||||
which will raise a ``RemovedInSphinx16Warning``.
|
||||
|
||||
* Sphinx 1.5 (the version that follows 1.4) will still contain the
|
||||
backwards-compatible replica.
|
||||
|
||||
* Sphinx 1.6 will remove the feature outright.
|
||||
|
||||
The warnings are displayed by default. You can turn off display of these
|
||||
warnings with:
|
||||
|
||||
* ``PYTHONWARNINGS= make html`` (Linux/Mac)
|
||||
* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
|
||||
* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
|
36
doc/_templates/index.html
vendored
36
doc/_templates/index.html
vendored
@ -46,18 +46,30 @@
|
||||
|
||||
<h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
|
||||
|
||||
<table class="contentstable"><tr>
|
||||
<td>
|
||||
<p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
|
||||
<p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
|
||||
</td><td>
|
||||
{%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
|
||||
{%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
|
||||
</td></tr>
|
||||
<table class="contentstable">
|
||||
<tr>
|
||||
<td>
|
||||
<p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
|
||||
</td><td>
|
||||
{%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
|
||||
</td>
|
||||
</tr><tr>
|
||||
<td>
|
||||
<p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
|
||||
</td><td>
|
||||
{%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
|
||||
</td>
|
||||
</tr><tr>
|
||||
<td>
|
||||
<p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
|
||||
<span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
|
||||
</td><td>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>{%trans%}
|
||||
|
4
doc/_templates/indexsidebar.html
vendored
4
doc/_templates/indexsidebar.html
vendored
@ -4,14 +4,14 @@
|
||||
|
||||
<h3>Download</h3>
|
||||
{% if version.endswith('a0') %}
|
||||
<p>{%trans%}This documentation is for version <b>{{ version }}</b>, which is
|
||||
<p>{%trans%}This documentation is for version <b><a href="changes.html">{{ version }}</a></b>, which is
|
||||
not released yet.{%endtrans%}</p>
|
||||
<p>{%trans%}You can use it from the
|
||||
<a href="https://github.com/sphinx-doc/sphinx/">Git repo</a> or look for
|
||||
released versions in the <a href="https://pypi.python.org/pypi/Sphinx">Python
|
||||
Package Index</a>.{%endtrans%}</p>
|
||||
{% else %}
|
||||
<p>{%trans%}Current version: <b>{{ version }}</b>{%endtrans%}</p>
|
||||
<p>{%trans%}Current version: <b><a href="changes.html">{{ version }}</a></b>{%endtrans%}</p>
|
||||
<p>{%trans%}Get Sphinx from the <a href="https://pypi.python.org/pypi/Sphinx">Python Package
|
||||
Index</a>, or install it with:{%endtrans%}</p>
|
||||
<pre>pip install -U Sphinx</pre>
|
||||
|
331
doc/devguide.rst
331
doc/devguide.rst
@ -1,331 +0,0 @@
|
||||
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 Git and is hosted on Github.
|
||||
|
||||
git clone git://github.com/sphinx-doc/sphinx
|
||||
|
||||
.. rubric:: Community
|
||||
|
||||
sphinx-users <sphinx-users@googlegroups.com>
|
||||
Mailing list for user support.
|
||||
|
||||
sphinx-dev <sphinx-dev@googlegroups.com>
|
||||
Mailing list for development related discussions.
|
||||
|
||||
#sphinx-doc on irc.freenode.net
|
||||
IRC channel for development questions and user support.
|
||||
|
||||
|
||||
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 Github 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`: 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 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
|
||||
**master** 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 Github.
|
||||
|
||||
#. 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. ::
|
||||
|
||||
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. ::
|
||||
|
||||
git checkout stable
|
||||
|
||||
For new features or other substantial changes that should wait until the
|
||||
next major release, use the ``master`` branch.
|
||||
|
||||
#. Optional: setup a virtual environment. ::
|
||||
|
||||
virtualenv ~/sphinxenv
|
||||
. ~/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`_.
|
||||
|
||||
#. Test, test, test. Possible steps:
|
||||
|
||||
* Run the unit tests::
|
||||
|
||||
pip install -r test-reqs.txt
|
||||
make test
|
||||
|
||||
* Again, it's useful to turn on deprecation warnings on so they're shown in
|
||||
the test output::
|
||||
|
||||
PYTHONWARNINGS=all make test
|
||||
|
||||
* Build the documentation and check the output for different builders::
|
||||
|
||||
cd doc
|
||||
make clean html 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.
|
||||
|
||||
* 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*.
|
||||
|
||||
#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not
|
||||
trivial (small doc updates, typo fixes). Then commit::
|
||||
|
||||
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::
|
||||
|
||||
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
|
||||
|
||||
would close issue #42.
|
||||
|
||||
#. Push changes in the branch to your forked repository on Github. ::
|
||||
|
||||
git push origin feature-xyz
|
||||
|
||||
#. 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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Locale updates
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The parts of messages in Sphinx that go into builds are translated into several
|
||||
locales. The translations are kept as gettext ``.po`` files translated from the
|
||||
master template ``sphinx/locale/sphinx.pot``.
|
||||
|
||||
Sphinx uses `Babel <http://babel.edgewall.org>`_ to extract messages and
|
||||
maintain the catalog files. It is integrated in ``setup.py``:
|
||||
|
||||
* Use ``python setup.py extract_messages`` to update the ``.pot`` template.
|
||||
* Use ``python setup.py update_catalog`` to update all existing language
|
||||
catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the
|
||||
template file.
|
||||
* Use ``python setup.py compile_catalog`` to compile the ``.po`` files to binary
|
||||
``.mo`` files and ``.js`` files.
|
||||
|
||||
When an updated ``.po`` file is submitted, run compile_catalog to commit both
|
||||
the source and the compiled catalogs.
|
||||
|
||||
When a new locale is submitted, add a new directory with the ISO 639-1 language
|
||||
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
|
||||
``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.
|
||||
|
||||
|
||||
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` if it's important enough.
|
||||
|
||||
* 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
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
* 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
|
||||
<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
|
||||
|
||||
Deprecating a feature
|
||||
---------------------
|
||||
|
||||
There are a couple reasons that code in Sphinx might be deprecated:
|
||||
|
||||
* If a feature has been improved or modified in a backwards-incompatible way,
|
||||
the old feature or behavior will be deprecated.
|
||||
|
||||
* Sometimes Sphinx will include a backport of a Python library that's not
|
||||
included in a version of Python that Sphinx currently supports. When Sphinx
|
||||
no longer needs to support the older version of Python that doesn't include
|
||||
the library, the library will be deprecated in Sphinx.
|
||||
|
||||
As the :ref:`deprecation-policy` describes,
|
||||
the first release of Sphinx that deprecates a feature (``A.B``) should raise a
|
||||
``RemovedInSphinxXXWarning`` (where XX is the Sphinx version where the feature
|
||||
will be removed) when the deprecated feature is invoked. Assuming we have good
|
||||
test coverage, these warnings are converted to errors when running the test
|
||||
suite with warnings enabled: ``python -Wall tests/run.py``. Thus, when adding
|
||||
a ``RemovedInSphinxXXWarning`` you need to eliminate or silence any warnings
|
||||
generated when running the tests.
|
||||
|
||||
.. _deprecation-policy:
|
||||
|
||||
Deprecation policy
|
||||
------------------
|
||||
|
||||
A feature release may deprecate certain features from previous releases. If a
|
||||
feature is deprecated in feature release 1.A, it will continue to work in all
|
||||
1.A.x versions (for all versions of x) but raise warnings. Deprecated features
|
||||
will be removed in the first 1.B release, or 1.B.1 for features deprecated in
|
||||
the last 1.A.x feature release to ensure deprecations are done over at least 2
|
||||
feature releases.
|
||||
|
||||
So, for example, if we decided to start the deprecation of a function in
|
||||
Sphinx 1.4:
|
||||
|
||||
* Sphinx 1.4.x will contain a backwards-compatible replica of the function
|
||||
which will raise a ``RemovedInSphinx16Warning``.
|
||||
|
||||
* Sphinx 1.5 (the version that follows 1.4) will still contain the
|
||||
backwards-compatible replica.
|
||||
|
||||
* Sphinx 1.6 will remove the feature outright.
|
||||
|
||||
The warnings are displayed by default. You can turn off display of these
|
||||
warnings with:
|
||||
|
||||
* ``PYTHONWARNINGS= make html`` (Linux/Mac)
|
||||
* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
|
||||
* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
|
1
doc/devguide.rst
Symbolic link
1
doc/devguide.rst
Symbolic link
@ -0,0 +1 @@
|
||||
../CONTRIBUTING.rst
|
@ -318,6 +318,11 @@ are recognized and formatted nicely:
|
||||
* ``returns``, ``return``: Description of the return value.
|
||||
* ``rtype``: Return type. Creates a link if possible.
|
||||
|
||||
.. note::
|
||||
|
||||
In current release, all ``var``, ``ivar`` and ``cvar`` are represented as "Variable".
|
||||
There is no difference at all.
|
||||
|
||||
The field names must consist of one of these keywords and an argument (except
|
||||
for ``returns`` and ``rtype``, which do not need an argument). This is best
|
||||
explained by an example::
|
||||
|
@ -384,6 +384,15 @@ You can also give one or more filenames on the command line after the source and
|
||||
build directories. Sphinx will then try to build only these output files (and
|
||||
their dependencies).
|
||||
|
||||
Environment variables
|
||||
---------------------
|
||||
|
||||
The :program:`sphinx-build` refers following environment variables:
|
||||
|
||||
.. describe:: MAKE
|
||||
|
||||
A path to make command. A command name is also allowed.
|
||||
:program:`sphinx-build` uses it to invoke sub-build process on make-mode.
|
||||
|
||||
Makefile options
|
||||
----------------
|
||||
|
@ -49,7 +49,7 @@ class toctree(nodes.General, nodes.Element, translatable):
|
||||
"""Node for inserting a "TOC tree"."""
|
||||
|
||||
def preserve_original_messages(self):
|
||||
if 'caption' in self:
|
||||
if self.get('caption'):
|
||||
self['rawcaption'] = self['caption']
|
||||
|
||||
def apply_translated_message(self, original_message, translated_message):
|
||||
|
@ -15,6 +15,7 @@ import re
|
||||
import sys
|
||||
import inspect
|
||||
import traceback
|
||||
import warnings
|
||||
from types import FunctionType, BuiltinFunctionType, MethodType
|
||||
|
||||
from six import PY2, iterkeys, iteritems, itervalues, text_type, class_types, \
|
||||
@ -588,7 +589,9 @@ class Documenter(object):
|
||||
for modname in self.env.config.autodoc_mock_imports:
|
||||
dbg('[autodoc] adding a mock module %s!', modname)
|
||||
mock_import(modname)
|
||||
__import__(self.modname)
|
||||
with warnings.catch_warnings():
|
||||
warnings.filterwarnings("ignore", category=ImportWarning)
|
||||
__import__(self.modname)
|
||||
parent = None
|
||||
obj = self.module = sys.modules[self.modname]
|
||||
dbg('[autodoc] => %r', obj)
|
||||
|
@ -63,6 +63,7 @@ class Make(object):
|
||||
self.srcdir = srcdir
|
||||
self.builddir = builddir
|
||||
self.opts = opts
|
||||
self.makecmd = os.environ.get('MAKE', 'make') # refer $MAKE to determine make command
|
||||
|
||||
def builddir_join(self, *comps):
|
||||
# type: (unicode) -> unicode
|
||||
@ -177,14 +178,14 @@ class Make(object):
|
||||
if self.run_generic_build('latex') > 0:
|
||||
return 1
|
||||
with cd(self.builddir_join('latex')):
|
||||
os.system('make all-pdf')
|
||||
os.system('%s all-pdf' % self.makecmd)
|
||||
|
||||
def build_latexpdfja(self):
|
||||
# type: () -> int
|
||||
if self.run_generic_build('latex') > 0:
|
||||
return 1
|
||||
with cd(self.builddir_join('latex')):
|
||||
os.system('make all-pdf-ja')
|
||||
os.system('%s all-pdf-ja' % self.makecmd)
|
||||
|
||||
def build_text(self):
|
||||
# type: () -> int
|
||||
@ -208,7 +209,7 @@ class Make(object):
|
||||
if self.run_generic_build('texinfo') > 0:
|
||||
return 1
|
||||
with cd(self.builddir_join('texinfo')):
|
||||
os.system('make info')
|
||||
os.system('%s info' % self.makecmd)
|
||||
|
||||
def build_gettext(self):
|
||||
# type: () -> int
|
||||
|
@ -18,11 +18,11 @@
|
||||
\RequirePackage{amstext}
|
||||
\RequirePackage{textcomp}
|
||||
\RequirePackage{titlesec}
|
||||
\AtBeginDocument{\@ifpackagelater{titlesec}{2016/03/15}%
|
||||
{\@ifpackagelater{titlesec}{2016/03/21}{}%
|
||||
{\AtEndDocument{\PackageWarningNoLine{sphinx}{^^J%
|
||||
\@ifpackagelater{titlesec}{2016/03/15}%
|
||||
{\@ifpackagelater{titlesec}{2016/03/21}{}%
|
||||
{\AtEndDocument{\PackageWarningNoLine{sphinx}{^^J%
|
||||
******** ERROR !! PLEASE UPDATE titlesec.sty !!********^^J%
|
||||
******** THIS VERSION SWALLOWS SECTION NUMBERS.********}}}}{}}
|
||||
******** THIS VERSION SWALLOWS SECTION NUMBERS.********}}}}{}
|
||||
\RequirePackage{tabulary}
|
||||
\RequirePackage{makeidx}
|
||||
% For framing code-blocks and warning type notices, and shadowing topics
|
||||
|
@ -39,16 +39,16 @@ class XapianSearch(BaseSearch):
|
||||
# Ensure the db lock is removed.
|
||||
del self.database
|
||||
|
||||
def add_document(self, path, title, text):
|
||||
def add_document(self, pagename, filename, title, text):
|
||||
self.database.begin_transaction()
|
||||
# sphinx_page_path is used to easily retrieve documents by path.
|
||||
sphinx_page_path = '"sphinxpagepath%s"' % path.replace('/', '_')
|
||||
sphinx_page_path = '"sphinxpagepath%s"' % pagename.replace('/', '_')
|
||||
# Delete the old document if it exists.
|
||||
self.database.delete_document(sphinx_page_path)
|
||||
|
||||
doc = xapian.Document()
|
||||
doc.set_data(text)
|
||||
doc.add_value(self.DOC_PATH, path)
|
||||
doc.add_value(self.DOC_PATH, pagename)
|
||||
doc.add_value(self.DOC_TITLE, title)
|
||||
self.indexer.set_document(doc)
|
||||
self.indexer.index_text(text)
|
||||
|
@ -142,7 +142,8 @@ class path(text_type):
|
||||
"""
|
||||
Returns the text in the file.
|
||||
"""
|
||||
with open(self, mode='U', encoding=encoding, **kwargs) as f:
|
||||
mode = 'rU' if PY2 else 'r'
|
||||
with open(self, mode=mode, encoding=encoding, **kwargs) as f:
|
||||
text = f.read()
|
||||
contents = repr_as(text, '<%s contents>' % self.basename())
|
||||
return contents
|
||||
|
@ -13,6 +13,7 @@ from __future__ import print_function
|
||||
|
||||
import os
|
||||
import sys
|
||||
import warnings
|
||||
import traceback
|
||||
|
||||
from path import path
|
||||
@ -48,4 +49,8 @@ tempdir.makedirs()
|
||||
print('Running Sphinx test suite (with Python %s)...' % sys.version.split()[0])
|
||||
sys.stdout.flush()
|
||||
|
||||
# filter warnings of test dependencies
|
||||
warnings.filterwarnings('ignore', category=DeprecationWarning, module='nose.util')
|
||||
warnings.filterwarnings('ignore', category=DeprecationWarning, module='site') # virtualenv
|
||||
|
||||
nose.main(argv=sys.argv)
|
||||
|
@ -9,15 +9,13 @@
|
||||
:license: BSD, see LICENSE for details.
|
||||
"""
|
||||
|
||||
from xml.etree import ElementTree
|
||||
|
||||
from util import with_app
|
||||
from util import with_app, etree_parse
|
||||
|
||||
|
||||
@with_app('xml', testroot='directive-code')
|
||||
def test_code_block(app, status, warning):
|
||||
app.builder.build('index')
|
||||
et = ElementTree.parse(app.outdir / 'index.xml')
|
||||
et = etree_parse(app.outdir / 'index.xml')
|
||||
secs = et.findall('./section/section')
|
||||
code_block = secs[0].findall('literal_block')
|
||||
assert len(code_block) > 0
|
||||
@ -33,7 +31,7 @@ def test_code_block(app, status, warning):
|
||||
@with_app('xml', testroot='directive-code')
|
||||
def test_code_block_dedent(app, status, warning):
|
||||
app.builder.build(['dedent_code'])
|
||||
et = ElementTree.parse(app.outdir / 'dedent_code.xml')
|
||||
et = etree_parse(app.outdir / 'dedent_code.xml')
|
||||
blocks = et.findall('./section/section/literal_block')
|
||||
|
||||
for i in range(5): # 0-4
|
||||
@ -94,7 +92,7 @@ def test_code_block_namedlink_latex(app, status, warning):
|
||||
@with_app('xml', testroot='directive-code')
|
||||
def test_literal_include(app, status, warning):
|
||||
app.builder.build(['index'])
|
||||
et = ElementTree.parse(app.outdir / 'index.xml')
|
||||
et = etree_parse(app.outdir / 'index.xml')
|
||||
secs = et.findall('./section/section')
|
||||
literal_include = secs[1].findall('literal_block')
|
||||
literal_src = (app.srcdir / 'literal.inc').text(encoding='utf-8')
|
||||
@ -109,7 +107,7 @@ def test_literal_include_dedent(app, status, warning):
|
||||
literal_lines = [l[4:] for l in literal_src.split('\n')[9:11]]
|
||||
|
||||
app.builder.build(['dedent'])
|
||||
et = ElementTree.parse(app.outdir / 'dedent.xml')
|
||||
et = etree_parse(app.outdir / 'dedent.xml')
|
||||
blocks = et.findall('./section/section/literal_block')
|
||||
|
||||
for i in range(5): # 0-4
|
||||
@ -124,7 +122,7 @@ def test_literal_include_dedent(app, status, warning):
|
||||
@with_app('xml', testroot='directive-code')
|
||||
def test_literal_include_block_start_with_comment_or_brank(app, status, warning):
|
||||
app.builder.build(['python'])
|
||||
et = ElementTree.parse(app.outdir / 'python.xml')
|
||||
et = etree_parse(app.outdir / 'python.xml')
|
||||
secs = et.findall('./section/section')
|
||||
literal_include = secs[0].findall('literal_block')
|
||||
assert len(literal_include) > 0
|
||||
@ -290,7 +288,7 @@ def test_literalinclude_namedlink_latex(app, status, warning):
|
||||
@with_app('xml', testroot='directive-code')
|
||||
def test_literalinclude_classes(app, status, warning):
|
||||
app.builder.build(['classes'])
|
||||
et = ElementTree.parse(app.outdir / 'classes.xml')
|
||||
et = etree_parse(app.outdir / 'classes.xml')
|
||||
secs = et.findall('./section/section')
|
||||
|
||||
code_block = secs[0].findall('literal_block')
|
||||
|
@ -26,7 +26,7 @@ def skip_if_graphviz_not_found(fn):
|
||||
dot = subprocess.Popen([graphviz_dot, '-V'],
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE) # show version
|
||||
dot.wait()
|
||||
dot.communicate()
|
||||
found = True
|
||||
except OSError: # No such file or directory
|
||||
pass
|
||||
|
@ -16,7 +16,6 @@ import re
|
||||
import pickle
|
||||
from docutils import nodes
|
||||
from subprocess import Popen, PIPE
|
||||
from xml.etree import ElementTree
|
||||
|
||||
from babel.messages import pofile
|
||||
from nose.tools import assert_equal
|
||||
@ -24,7 +23,7 @@ from six import string_types
|
||||
|
||||
from util import tempdir, rootdir, path, gen_with_app, with_app, SkipTest, \
|
||||
assert_re_search, assert_not_re_search, assert_in, assert_not_in, \
|
||||
assert_startswith, assert_node, repr_as
|
||||
assert_startswith, assert_node, repr_as, etree_parse
|
||||
|
||||
|
||||
root = tempdir / 'test-intl'
|
||||
@ -502,7 +501,7 @@ def test_xml_builder(app, status, warning):
|
||||
|
||||
# --- footnotes: regression test for fix #955, #1176
|
||||
|
||||
et = ElementTree.parse(app.outdir / 'footnote.xml')
|
||||
et = etree_parse(app.outdir / 'footnote.xml')
|
||||
secs = et.findall('section')
|
||||
|
||||
para0 = secs[0].findall('paragraph')
|
||||
@ -542,7 +541,7 @@ def test_xml_builder(app, status, warning):
|
||||
|
||||
# --- footnote backlinks: i18n test for #1058
|
||||
|
||||
et = ElementTree.parse(app.outdir / 'footnote.xml')
|
||||
et = etree_parse(app.outdir / 'footnote.xml')
|
||||
secs = et.findall('section')
|
||||
|
||||
para0 = secs[0].findall('paragraph')
|
||||
@ -558,7 +557,7 @@ def test_xml_builder(app, status, warning):
|
||||
|
||||
# --- refs in the Python domain
|
||||
|
||||
et = ElementTree.parse(app.outdir / 'refs_python_domain.xml')
|
||||
et = etree_parse(app.outdir / 'refs_python_domain.xml')
|
||||
secs = et.findall('section')
|
||||
|
||||
# regression test for fix #1363
|
||||
@ -570,7 +569,7 @@ def test_xml_builder(app, status, warning):
|
||||
|
||||
# --- keep external links: regression test for #1044
|
||||
|
||||
et = ElementTree.parse(app.outdir / 'external_links.xml')
|
||||
et = etree_parse(app.outdir / 'external_links.xml')
|
||||
secs = et.findall('section')
|
||||
|
||||
para0 = secs[0].findall('paragraph')
|
||||
@ -623,7 +622,7 @@ def test_xml_builder(app, status, warning):
|
||||
|
||||
# --- role xref: regression test for #1090, #1193
|
||||
|
||||
et = ElementTree.parse(app.outdir / 'role_xref.xml')
|
||||
et = etree_parse(app.outdir / 'role_xref.xml')
|
||||
sec1, sec2 = et.findall('section')
|
||||
|
||||
para1, = sec1.findall('paragraph')
|
||||
@ -674,7 +673,7 @@ def test_xml_builder(app, status, warning):
|
||||
|
||||
# --- label targets: regression test for #1193, #1265
|
||||
|
||||
et = ElementTree.parse(app.outdir / 'label_target.xml')
|
||||
et = etree_parse(app.outdir / 'label_target.xml')
|
||||
secs = et.findall('section')
|
||||
|
||||
para0 = secs[0].findall('paragraph')
|
||||
|
@ -11,7 +11,9 @@ import os
|
||||
import re
|
||||
import sys
|
||||
import tempfile
|
||||
import warnings
|
||||
from functools import wraps
|
||||
from xml.etree import ElementTree
|
||||
|
||||
from six import StringIO, string_types
|
||||
|
||||
@ -155,6 +157,12 @@ def skip_unless_importable(module, msg=None):
|
||||
return skip_if(False, msg)
|
||||
|
||||
|
||||
def etree_parse(path):
|
||||
with warnings.catch_warnings(record=False):
|
||||
warnings.filterwarnings("ignore", category=DeprecationWarning)
|
||||
return ElementTree.parse(path)
|
||||
|
||||
|
||||
class Struct(object):
|
||||
def __init__(self, **kwds):
|
||||
self.__dict__.update(kwds)
|
||||
|
Loading…
Reference in New Issue
Block a user