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

Finalized #418 (#433)

Browse Source 
Cleanup README.rst

* Refactor list items.
* Use autonumbering in lists to prevent errors.
* Indent code inside list items to make it belong to those items.
* Use inline-code style for filenames.
* Update link to a pull request with new repo path.
* Fix a few typos and punctuation.
* Use .. code:: bash for proper highlighting
* Use # for comments in bash
* Use ordered list for step-by-step instuctions.

* Make all code blocks 4 space indents
This commit is contained in:
Benjamin Bach 2017-06-17 20:42:04 +02:00 committed by Aaron Carlisle
parent 71b90d076d
commit 93e6fe24bc
1 changed files with 34 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
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()]
Via git or download Via git or download
@ -53,7 +51,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
@ -110,7 +108,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
@ -149,8 +147,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
@ -174,7 +171,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
------ ------
@ -188,7 +185,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.
@ -217,30 +214,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 pip install sphinx
2. Install sass #. Install sass.
.. code:: .. code:: bash
gem install sass 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 brew install node
// Install bower and grunt # Install bower and grunt
npm install -g bower grunt-cli 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 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:
@ -249,13 +246,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
-------------------------- --------------------------
@ -274,14 +271,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
==== ====