Skip to content

Commit

Permalink
Cleanup README.rst:
Browse files Browse the repository at this point in the history 
* 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.
  • Loading branch information
@NickVolynkin
NickVolynkin committed Apr 28, 2017
1 parent aedac3d commit a1c6887
Showing 1 changed file with 44 additions and 47 deletions.
91 changes: 44 additions & 47 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,23 +42,21 @@ 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()]
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
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
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]
Configuration
=============
Expand All @@ -74,11 +72,11 @@ file of this repository, and can be defined in your project's ``conf.py`` via

.. code:: python
html_theme_options = {
'collapse_navigation': False,
'display_version': False,
'navigation_depth': 3,
}
html_theme_options = {
'collapse_navigation': False,
'display_version': False,
'navigation_depth': 3,
}
The following options are available:

Expand Down Expand Up @@ -110,7 +108,7 @@ master
* Hide Edit links on auto created pages
* Align ``.. centered::`` text to the center
* 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
* Fix padding on field lists

Expand Down Expand Up @@ -149,8 +147,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
Expand All @@ -174,7 +171,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
------
Expand All @@ -188,7 +185,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.

Expand Down Expand Up @@ -217,45 +214,45 @@ 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
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
brew install node
# Install node
brew install node
// Install bower and grunt
npm install -g bower grunt-cli
# Install bower and grunt
npm install -g bower grunt-cli
// Now that everything is installed, let's install the theme dependecies.
npm install
# 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:

.. code::
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
--------------------------
Expand All @@ -274,14 +271,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
====
Expand Down

0 comments on commit a1c6887

Please sign in to comment.