mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
Merge branch 'master' into style-cpp-domain
This commit is contained in:
Anthony
GitHub
@@ -17,6 +17,8 @@ Other Changes
|
||||
--------------
|
||||
|
||||
* Add the ``navigation`` template block around the navigation area.
|
||||
* Added Spanish translation
|
||||
* Added i18n support using Babel
|
||||
|
||||
0.4.3
|
||||
======
|
||||
@@ -93,7 +95,7 @@ Fixes
|
||||
* Color accessibility improvements on the left navigation
|
||||
|
||||
Other Changes
|
||||
--------------
|
||||
---------------
|
||||
|
||||
* Write theme version and build date at top of JavaScript and CSS
|
||||
* Changed code and literals to use a native font stack (#612)
|
||||
|
||||
@@ -4,11 +4,11 @@ import sys
|
||||
import os
|
||||
import re
|
||||
|
||||
sys.path.append(os.path.abspath('..'))
|
||||
if not 'READTHEDOCS' in os.environ:
|
||||
sys.path.insert(0, os.path.abspath('..'))
|
||||
sys.path.append(os.path.abspath('./demo/'))
|
||||
|
||||
from sphinx.locale import _
|
||||
|
||||
from sphinx_rtd_theme import __version__
|
||||
|
||||
|
||||
@@ -26,11 +26,14 @@ extensions = [
|
||||
'sphinx.ext.mathjax',
|
||||
'sphinx.ext.viewcode',
|
||||
'sphinxcontrib.httpdomain',
|
||||
'sphinx_rtd_theme',
|
||||
]
|
||||
|
||||
templates_path = ['_templates']
|
||||
source_suffix = '.rst'
|
||||
exclude_patterns = []
|
||||
locale_dirs = ['locale/']
|
||||
gettext_compact = False
|
||||
|
||||
master_doc = 'index'
|
||||
suppress_warnings = ['image.nonlocal_uri']
|
||||
|
||||
@@ -1,89 +1,113 @@
|
||||
************
|
||||
Contributing
|
||||
************
|
||||
|
||||
***********************************
|
||||
Contributing or modifying the theme
|
||||
***********************************
|
||||
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.
|
||||
|
||||
The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm
|
||||
using bower_ to manage these dependencies and sass_ to build the css. The good news is
|
||||
I have a very nice set of grunt_ operations that will not only load these dependencies, but watch
|
||||
for changes, rebuild the sphinx demo docs and build a distributable version of the theme.
|
||||
The bad news is this means you'll need to set up your environment similar to that
|
||||
of a front-end developer (vs. that of a python developer). That means installing node and ruby.
|
||||
Modifying the theme
|
||||
===================
|
||||
|
||||
.. seealso::
|
||||
|
||||
If you are unsure of appropriate actions to take while interacting with our
|
||||
community please read our :doc:`Code of Conduct <rtd:code-of-conduct>`.
|
||||
The styles for this theme use SASS_ and a custom CSS framework called Wyrm_. We
|
||||
use Bower_ to manage these dependencies and SASS_ to build the CSS. Grunt_ is
|
||||
used to watch for changes, rebuild the static assets, and rebuild the Sphinx
|
||||
demo documentation.
|
||||
|
||||
.. note::
|
||||
The installation of Ruby and Node is outside the scope of this
|
||||
documentation. You will need both in order to make changes to this theme.
|
||||
|
||||
Set up your environment
|
||||
=======================
|
||||
-----------------------
|
||||
|
||||
#. Install sphinx_ into a virtual environment.
|
||||
#. Install Sphinx_ and documentation build dependencies.
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
pip install sphinx sphinxcontrib-httpdomain
|
||||
pip install -e '.[dev]'
|
||||
|
||||
#. Install sass.
|
||||
#. Install SASS.
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
gem install sass
|
||||
|
||||
#. Install node, bower, grunt, and theme dependencies.
|
||||
#. Install Bower, Grunt, and theme dependencies locally.
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
# Install node
|
||||
brew install node
|
||||
|
||||
# Install bower and grunt
|
||||
npm install -g bower grunt-cli
|
||||
|
||||
# Now that everything is installed, let's install the theme dependencies.
|
||||
npm install
|
||||
|
||||
Now that our environment is set up, make sure you're in your virtual environment, go to
|
||||
this repository in your terminal and run grunt:
|
||||
Making changes
|
||||
--------------
|
||||
|
||||
.. code::
|
||||
Changes to the theme can be compiled and tested with the default Grunt task:
|
||||
|
||||
.. code:: console
|
||||
|
||||
grunt
|
||||
|
||||
This default task will do the following **very cool things that make it worth the trouble**:
|
||||
This default task will do the following:
|
||||
|
||||
#. Install and update any bower dependencies.
|
||||
#. Run sphinx and build new docs.
|
||||
#. Watch for changes to the sass files and build css from the changes.
|
||||
#. Rebuild the sphinx docs anytime it notices a change to ``.rst``, ``.html``, ``.js``
|
||||
or ``.css`` files.
|
||||
#. Install and update any Bower 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.
|
||||
|
||||
.. _bower: http://www.bower.io
|
||||
.. _sass: http://www.sass-lang.com
|
||||
.. _wyrm: http://www.github.com/snide/wyrm/
|
||||
.. _grunt: http://www.gruntjs.com
|
||||
.. _node: http://www.nodejs.com
|
||||
.. _sphinx: http://www.sphinx-doc.org/en/stable/
|
||||
Alternatively, if you don't need to watch the files, Grunt can be called with
|
||||
the same task used for releases:
|
||||
|
||||
.. code:: console
|
||||
|
||||
Releasing the Theme
|
||||
grunt build
|
||||
|
||||
.. _Bower: http://www.bower.io
|
||||
.. _SASS: http://www.sass-lang.com
|
||||
.. _Wyrm: http://www.github.com/snide/wyrm/
|
||||
.. _Grunt: http://www.gruntjs.com
|
||||
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
|
||||
|
||||
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
|
||||
===================
|
||||
|
||||
When you release a new version,
|
||||
you should do the following:
|
||||
To release a new version of the theme, core team will take the following steps:
|
||||
|
||||
#. Bump the version in ``sphinx_rtd_theme/__init__.py``, ``bower.json`` and ``package.json`` --
|
||||
we try to follow `semver <http://semver.org/>`_, so be careful with breaking changes.
|
||||
#. Update the changelog (``docs/changelog.rst``) with the version information.
|
||||
#. Run a ``grunt build`` to rebuild all the theme assets.
|
||||
#. Run ``grunt build`` to rebuild all the theme assets.
|
||||
#. Run ``python setup.py update_translations`` to compile new translation files and update Transifex
|
||||
#. Commit that change.
|
||||
#. Tag the release in git: ``git tag $NEW_VERSION``.
|
||||
#. Push the tag to GitHub: ``git push --tags origin``.
|
||||
#. Upload the package to PyPI:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
$ rm -rf dist/
|
||||
$ python setup.py sdist bdist_wheel
|
||||
$ twine upload --sign --identity security@readthedocs.org dist/*
|
||||
rm -rf dist/
|
||||
python setup.py sdist bdist_wheel
|
||||
twine upload --sign --identity security@readthedocs.org dist/*
|
||||
|
||||
@@ -6,14 +6,18 @@
|
||||
|
||||
installing
|
||||
configuring
|
||||
changelog
|
||||
contributing
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:hidden:
|
||||
|
||||
changelog
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
:caption: Demo Documents
|
||||
:caption: Demo Documentation
|
||||
|
||||
demo/structure
|
||||
demo/demo
|
||||
|
||||
@@ -1,14 +1,10 @@
|
||||
|
||||
************
|
||||
Installation
|
||||
************
|
||||
|
||||
Via Python Package
|
||||
==================
|
||||
|
||||
Install the package (or add it to your ``requirements.txt`` file):
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
pip install sphinx_rtd_theme
|
||||
|
||||
@@ -16,8 +12,22 @@ In your ``conf.py`` file:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import sphinx_rtd_theme
|
||||
|
||||
extensions = [
|
||||
...
|
||||
'sphinx_rtd_theme',
|
||||
]
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
|
||||
|
||||
.. note::
|
||||
Adding this theme as an extension is what enables localization of theme
|
||||
strings in your translated output. If these strings are not translated in
|
||||
your output, either we lack the localized strings for your locale, or you
|
||||
are using an old version of the theme.
|
||||
|
||||
Via Git or Download
|
||||
===================
|
||||
|
||||
@@ -29,4 +39,3 @@ Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into you
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
html_theme_path = ["_themes", ]
|
||||
|
||||
|
||||
@@ -1,2 +1,2 @@
|
||||
sphinxcontrib-httpdomain
|
||||
sphinx
|
||||
sphinxcontrib-httpdomain
|
||||
|
||||
Reference in New Issue
Block a user