mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
Merge branch 'master' into setuptools-entry-points
This commit is contained in:
Aaron Carlisle
GitHub
commit
c6d926e1cf
59
README.rst
59
README.rst
@ -43,9 +43,7 @@ In your ``conf.py`` file:
|
||||
.. code:: python
|
||||
|
||||
import sphinx_rtd_theme
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
|
||||
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
|
||||
``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
|
||||
conf.py file:
|
||||
``conf.py`` file:
|
||||
|
||||
.. code:: python
|
||||
|
||||
@ -157,8 +155,7 @@ v0.2.0
|
||||
v0.1.10-alpha
|
||||
-------------
|
||||
|
||||
.. note::
|
||||
This is a pre-release version
|
||||
.. note:: This is a pre-release version
|
||||
|
||||
* Removes Sphinx dependency
|
||||
* Fixes hamburger on mobile display
|
||||
@ -182,7 +179,7 @@ v0.1.9
|
||||
* Fixed modernizr URL
|
||||
* 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
|
||||
------
|
||||
@ -196,7 +193,7 @@ v0.1.8
|
||||
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
|
||||
docs. If no toctrees are set the theme reverts to sphinx's usual local toctree.
|
||||
|
||||
@ -225,29 +222,29 @@ of a front-end developer (vs. that of a python developer). That means installing
|
||||
Set up your environment
|
||||
-----------------------
|
||||
|
||||
1. Install sphinx_ into a virtual environment.
|
||||
#. Install sphinx_ into a virtual environment.
|
||||
|
||||
.. code::
|
||||
.. code:: bash
|
||||
|
||||
pip install sphinx
|
||||
pip install sphinx sphinxcontrib-httpdomain
|
||||
|
||||
2. Install sass
|
||||
#. Install sass.
|
||||
|
||||
.. code::
|
||||
.. code:: bash
|
||||
|
||||
gem install sass
|
||||
|
||||
2. Install node, bower and grunt.
|
||||
#. Install node, bower, grunt, and theme dependencies.
|
||||
|
||||
.. code::
|
||||
.. code:: bash
|
||||
|
||||
// Install node
|
||||
# Install node
|
||||
brew install node
|
||||
|
||||
// Install bower and grunt
|
||||
# Install bower and grunt
|
||||
npm install -g bower grunt-cli
|
||||
|
||||
// Now that everything is installed, let's install the theme dependecies.
|
||||
# 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
|
||||
@ -257,13 +254,13 @@ this repository in your terminal and run 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.
|
||||
2. It'll run sphinx and build new docs.
|
||||
3. It'll 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
|
||||
or .css files.
|
||||
#. 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.
|
||||
|
||||
Before you create an issue
|
||||
--------------------------
|
||||
@ -282,14 +279,14 @@ Releasing the Theme
|
||||
When you release a new version,
|
||||
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.
|
||||
* Run a ``grunt build`` to rebuild all the theme assets.
|
||||
* 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: ``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, run ``gulp build`` to update the distributed theme files
|
||||
#. 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.
|
||||
#. 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: ``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, run ``gulp build`` to update the distributed theme files.
|
||||
|
||||
TODO
|
||||
====
|
||||
|
||||
Loading…
Reference in New Issue
Block a user