IntenseWebs/sphinx_rtd_theme
3
0
Fork 0
mirror of https://github.com/readthedocs/sphinx_rtd_theme.git synced 2025-02-25 18:55:21 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into setuptools-entry-points

Browse Source
This commit is contained in:
Aaron Carlisle 2017-06-17 18:33:01 -04:00 committed by GitHub
commit c6d926e1cf
1 changed files with 35 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
README.rst
View File

@ -36,16 +36,14 @@ Download the package or add it to your ``requirements.txt`` file:
.. code:: bash .. code:: bash
pip install sphinx_rtd_theme pip install sphinx_rtd_theme
In your ``conf.py`` file: In your ``conf.py`` file:
.. code:: python .. code:: python
import sphinx_rtd_theme import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme" html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
or (since master): or (since master):
@ -59,7 +57,7 @@ Via git or download
Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx ``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
conf.py file: ``conf.py`` file:
.. code:: python .. code:: python
@ -116,7 +114,7 @@ master
* Hide Edit links on auto created pages * Hide Edit links on auto created pages
* Align ``.. centered::`` text to the center * Align ``.. centered::`` text to the center
* Increase contrast for footnotes * Increase contrast for footnotes
* Add language to the JS output variable * Add language to the JS output variable
* Include the lato italics font with the theme * Include the lato italics font with the theme
* Fix padding on field lists * Fix padding on field lists
* Add setuptools entry point allowing to use ``sphinx_rtd_theme`` as * Add setuptools entry point allowing to use ``sphinx_rtd_theme`` as
@ -157,8 +155,7 @@ v0.2.0
v0.1.10-alpha v0.1.10-alpha
------------- -------------
.. note:: .. note:: This is a pre-release version
This is a pre-release version
* Removes Sphinx dependency * Removes Sphinx dependency
* Fixes hamburger on mobile display * Fixes hamburger on mobile display
@ -182,7 +179,7 @@ v0.1.9
* Fixed modernizr URL * Fixed modernizr URL
* Small display style changes on code blocks, figure captions, and nav elements * Small display style changes on code blocks, figure captions, and nav elements
.. _#215: https://github.com/snide/sphinx_rtd_theme/pull/215 .. _#215: https://github.com/rtfd/sphinx_rtd_theme/pull/215
v0.1.8 v0.1.8
------ ------
@ -196,7 +193,7 @@ v0.1.8
How the Table of Contents builds How the Table of Contents builds
================================ ================================
Currently the left menu will build based upon any ``toctree(s)`` defined in your index.rst file. Currently the left menu will build based upon any ``toctree(s)`` defined in your ``index.rst`` file.
It outputs 2 levels of depth, which should give your visitors a high level of access to your It outputs 2 levels of depth, which should give your visitors a high level of access to your
docs. If no toctrees are set the theme reverts to sphinx's usual local toctree. docs. If no toctrees are set the theme reverts to sphinx's usual local toctree.
@ -225,30 +222,30 @@ of a front-end developer (vs. that of a python developer). That means installing
Set up your environment Set up your environment
----------------------- -----------------------
1. Install sphinx_ into a virtual environment. #. Install sphinx_ into a virtual environment.
.. code:: .. code:: bash
pip install sphinx sphinxcontrib-httpdomain
pip install sphinx #. Install sass.
2. Install sass .. code:: bash
.. code:: gem install sass
gem install sass #. Install node, bower, grunt, and theme dependencies.
2. Install node, bower and grunt. .. code:: bash
.. code:: # Install node
brew install node
// Install node # Install bower and grunt
brew install node npm install -g bower grunt-cli
// Install bower and grunt # Now that everything is installed, let's install the theme dependencies.
npm install -g bower grunt-cli npm install
// Now that everything is installed, let's install the theme dependecies.
npm install
Now that our environment is set up, make sure you're in your virtual environment, go to 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: this repository in your terminal and run grunt:
@ -257,13 +254,13 @@ this repository in your terminal and run grunt:
grunt grunt
This default task will do the following **very cool things that make it worth the trouble**. This default task will do the following **very cool things that make it worth the trouble**:
1. It'll install and update any bower dependencies. #. Install and update any bower dependencies.
2. It'll run sphinx and build new docs. #. Run sphinx and build new docs.
3. It'll watch for changes to the sass files and build css from the changes. #. Watch for changes to the sass files and build css from the changes.
4. It'll rebuild the sphinx docs anytime it notices a change to .rst, .html, .js #. Rebuild the sphinx docs anytime it notices a change to ``.rst``, ``.html``, ``.js``
or .css files. or ``.css`` files.
Before you create an issue Before you create an issue
-------------------------- --------------------------
@ -282,14 +279,14 @@ Releasing the Theme
When you release a new version, When you release a new version,
you should do the following: you should do the following:
* Bump the version in ``sphinx_rtd_theme/__init__.py`` - we try to follow `semver <http://semver.org/>`_, so be careful with breaking changes. #. Bump the version in ``sphinx_rtd_theme/__init__.py`` – we try to follow `semver <http://semver.org/>`_, so be careful with breaking changes.
* Run a ``grunt build`` to rebuild all the theme assets. #. Run a ``grunt build`` to rebuild all the theme assets.
* Commit that change #. Commit that change.
* Tag the release in git: ``git tag $NEW_VERSION``. #. Tag the release in git: ``git tag $NEW_VERSION``.
* Push the tag to GitHub: ``git push --tags origin`` #. Push the tag to GitHub: ``git push --tags origin``.
* Upload the package to PyPI: ``python setup.py sdist bdist_wheel upload`` #. Upload the package to PyPI: ``python setup.py sdist bdist_wheel upload``.
* In the ``readthedocs.org`` repo, edit the ``bower.json`` file to point at the correct version (``sphinx-rtd-theme": "https://github.com/rtfd/sphinx-rtd-theme.git#$NEW_VERSION"``) #. In the ``readthedocs.org`` repo, edit the ``bower.json`` file to point at the correct version (``sphinx-rtd-theme": "https://github.com/rtfd/sphinx-rtd-theme.git#$NEW_VERSION"``).
* In the ``readthedocs.org`` repo, run ``gulp build`` to update the distributed theme files #. In the ``readthedocs.org`` repo, run ``gulp build`` to update the distributed theme files.
TODO TODO
==== ====