mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
239 lines
8.1 KiB
ReStructuredText
239 lines
8.1 KiB
ReStructuredText
************
|
|
Contributing
|
|
************
|
|
|
|
This project follows the Read the Docs :doc:`code of conduct
|
|
<rtd:code-of-conduct>`. If you are not familiar with our code of conduct policy,
|
|
take a minute to read the policy before starting with your first contribution.
|
|
|
|
.. tip::
|
|
There is a new dockerized build environment, see :ref:`dockerized-build`.
|
|
|
|
Modifying the theme
|
|
===================
|
|
|
|
The styles for this theme use SASS_ and a custom CSS framework called Wyrm_. We
|
|
use Webpack_ and node-sass_ to build the CSS. Webpack_ is used to watch for
|
|
changes, rebuild the static assets, and rebuild the Sphinx demo documentation.
|
|
|
|
.. note::
|
|
The installation of Node is outside the scope of this documentation. You
|
|
will need Node version 10+ in order to make changes to this theme.
|
|
|
|
Set up your environment
|
|
-----------------------
|
|
|
|
#. Install Sphinx_ and documentation build dependencies.
|
|
|
|
.. code:: console
|
|
|
|
$ pip install -e '.[dev]'
|
|
|
|
#. Install Webpack_, node-sass_, and theme dependencies locally.
|
|
|
|
.. code:: console
|
|
|
|
$ npm install
|
|
|
|
Making changes
|
|
--------------
|
|
|
|
Changes to the theme can be compiled and tested with Webpack_:
|
|
|
|
.. code:: console
|
|
|
|
$ npm run dev
|
|
|
|
This script will do the following:
|
|
|
|
#. Install and update any dependencies.
|
|
#. Build the static CSS from SASS source files.
|
|
#. Build the demo documentation.
|
|
#. Watch for changes to the SASS files and documentation and rebuild everything
|
|
on any detected changes.
|
|
|
|
Alternatively, if you don't need to watch the files, the release build script
|
|
can be used to test built assets:
|
|
|
|
.. code:: console
|
|
|
|
$ npm run build
|
|
|
|
.. _Webpack: https://webpack.js.org/
|
|
.. _node-sass: https://github.com/sass/node-sass
|
|
.. _SASS: http://www.sass-lang.com
|
|
.. _Wyrm: http://www.github.com/snide/wyrm/
|
|
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
|
|
|
|
|
|
_dockerized-build::
|
|
|
|
Dockerized development
|
|
======================
|
|
|
|
If you have Docker available on your platform, you can get started building CSS and JS artifacts a bit faster and won't have to worry about any of the setup spilling over into your general environment.
|
|
|
|
When building with Docker, we create an image containing the build dependencies. Some of these are quite outdated and therefore ideal to isolate a container. The image is tagged as ``sphinx_rtd_theme:latest``.
|
|
|
|
Inside the running docker image, we mount the working copy of the repository, build the artifacts and finally observe that the artifacts have been built and left in your current git checkout.
|
|
|
|
Use the following steps:
|
|
|
|
.. code-block:: console
|
|
|
|
# Builds an updated version of the docker image
|
|
$ make docker-images
|
|
|
|
# Runs the docker environment and builds the assets. The container exits after completing the build.
|
|
$ make docker-run command=build
|
|
|
|
# Runs the development webserver
|
|
$ make docker-run command=dev
|
|
|
|
|
|
Every time you change the Node or Python requirements, you will need to rebuild images with ``make docker-images``. If you change SASS or JS, you will need to rebuild assets.
|
|
|
|
If you need a different setup, refer to ``Makefile`` to see the exact method used to invoke the Docker environment.
|
|
|
|
Testing
|
|
=======
|
|
|
|
QA testing theme changes and pull requests is complex, due to backwards
|
|
compatibility.
|
|
|
|
The following cases need to be tested with changes to CSS or JavaScript:
|
|
|
|
* Multiple, modern browsers should be tested. We officially support back
|
|
to IE11 at the moment
|
|
* Multiple viewport sizes should be tested for changes. We support large,
|
|
tablet, and mobile viewport sizes
|
|
* We currently support both the Sphinx HTML4 writer and HTML5 writer. This makes
|
|
for some complex CSS selectors
|
|
* Multiple major versions of Sphinx should be tested. We currently support back
|
|
to Sphinx version ``1.6``
|
|
|
|
It's easiest to test combinations of dependency versions using ``tox``:
|
|
|
|
.. code:: console
|
|
|
|
% tox -e py3-sphinx34-html4
|
|
|
|
If the tests and build are successful, you can view the built documentation at
|
|
the directory noted by Sphinx:
|
|
|
|
.. code:: console
|
|
|
|
build succeeded, 10 warnings.
|
|
|
|
The HTML pages are in .tox/py3-sphinx34-html4/tmp/html.
|
|
___________________________ summary ___________________________
|
|
py3-sphinx34-html4: commands succeeded
|
|
congratulations :)
|
|
|
|
You can then open up this path with a series of browsers to test.
|
|
|
|
The best way to spot UI issues is to compare two or more builds. You can build
|
|
multiple ``tox`` environments, and open both up for comparison:
|
|
|
|
.. code:: console
|
|
|
|
% tox -e py3-sphinx34-html4
|
|
...
|
|
% tox -e py3-sphinx34-html5
|
|
...
|
|
% firefox .tox/py3-sphinx34-html4/tmp/html/index.html
|
|
% firefox .tox/py3-sphinx34-html5/tmp/html/index.html
|
|
|
|
You can also use a separate ``tox`` environment for building output to compare
|
|
against. All of the ``tox`` environments have an additional postfix, ``-qa``, to
|
|
allow building the same environment twice, without overwriting any files. In
|
|
this test scenario, you would build from a branch or tag before building the
|
|
same ``tox`` environment for the pull request branch you are testing.
|
|
|
|
For example, to test against the tag ``0.5.2``:
|
|
|
|
.. code:: console
|
|
|
|
% git checkout 0.5.2
|
|
% tox -e py3-sphinx34-html4-qa
|
|
...
|
|
% git checkout feature/example-pull-request
|
|
% tox -e py3-sphinx34-html4
|
|
...
|
|
% firefox .tox/py3-sphinx34-html4-qa/tmp/html/index.html
|
|
% firefox .tox/py3-sphinx34-html4/tmp/html/index.html
|
|
|
|
Currently, the most important environments to QA are:
|
|
|
|
.. This list is purposely shorter than what we describe above. If we test all of
|
|
the cases above, we'll be here all day. Python 3, HTML4/5 writer, and latest
|
|
minor of each major Sphinx release should give us enough work.
|
|
|
|
* ``py3-sphinx18-html4``
|
|
* ``py3-sphinx18-html5``
|
|
* ``py3-sphinx24-html4``
|
|
* ``py3-sphinx24-html5``
|
|
* ``py3-sphinx35-html4``
|
|
* ``py3-sphinx35-html5``
|
|
* ``py3-sphinx41-html4``
|
|
* ``py3-sphinx41-html5``
|
|
|
|
Translations
|
|
============
|
|
|
|
Translations are managed using `Transifex`_. You can join any of the existing
|
|
language teams or request a new language is added to the project. For more
|
|
information on our translation standards, see our docs on
|
|
:doc:`rtd:development/i18n`
|
|
|
|
Periodically, core team should update the translation files outside our normal
|
|
releases. Someone from the core team, with write access to Transifex, should run
|
|
the following:
|
|
|
|
.. code:: console
|
|
|
|
$ python setup.py update_translations
|
|
|
|
This will extract new messages, upload the messages to Transifex, and will
|
|
update our local translation files. Changes can be checked in to a branch and
|
|
put up for review.
|
|
|
|
.. _Transifex: https://www.transifex.com/readthedocs/sphinx-rtd-theme
|
|
|
|
Releasing the theme
|
|
===================
|
|
|
|
To release a new version of the theme, core team will take the following steps:
|
|
|
|
#. Bump the version by running ``bump2version [major|minor|patch|dev]``.
|
|
This will automatically increase the correct part(s) of the version number,
|
|
you do not need to specify the exact version number.
|
|
We follow `semantic versioning`_ and `PEP440`_
|
|
(with regards to alpha release and development versions). The version
|
|
increment should reflect these releases and any potentially breaking changes.
|
|
#. New versions are by default ``alpha`` releases. If this is a release candidate,
|
|
run ``bump2version --allow-dirty release`` to update the release to an ``rc``
|
|
release. If this is a final release, run the command again.
|
|
#. Update the changelog (``docs/changelog.rst``) with the version information.
|
|
#. Run ``python setup.py update_translations`` to compile new translation files
|
|
and update Transifex.
|
|
#. Run ``python setup.py build_assets`` to rebuild all the theme assets and the Python
|
|
package.
|
|
#. Commit these changes.
|
|
#. Tag the release in git: ``git tag $NEW_VERSION``.
|
|
#. Push the tag to GitHub: ``git push --tags origin``.
|
|
#. Upload the package to PyPI:
|
|
|
|
.. code:: console
|
|
|
|
$ rm -rf dist/
|
|
$ python setup.py sdist bdist_wheel
|
|
$ twine upload --sign --identity security@readthedocs.org dist/*
|
|
|
|
#. Finally, open a new pull request updating the development release version to
|
|
the next patch by running ``bump2version patch``. Open a pull request with
|
|
this change.
|
|
|
|
.. _PEP440: https://www.python.org/dev/peps/pep-0440/
|
|
.. _semantic versioning: http://semver.org/
|