Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Finalized #418 #433

Merged
merged 2 commits into from
Jun 17, 2017
Merged

Finalized #418 #433

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c29585a
Cleanup README.rst:
NickVolynkin Apr 28, 2017
1bcb756
Make all code blocks 4 space indents
benjaoming Jun 16, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 34 additions & 37 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,24 +36,22 @@ Download the package or add it to your ``requirements.txt`` file:

.. code:: bash

pip install sphinx_rtd_theme
pip install sphinx_rtd_theme

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()]

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

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,30 +214,30 @@ 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:
Expand All @@ -249,13 +246,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
--------------------------
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