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

Cleanup README.rst: #418

Closed
wants to merge 1 commit into from
Closed

Cleanup README.rst: #418

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
91 changes: 44 additions & 47 deletions README.rst
View file
Open in desktop
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", ]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be 4 space indent


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,
}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4 space indent here


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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This code block would be 7 space indent (3 for list item, 4 for code)


2. Install sass
#. Install sass.

.. code::
.. code:: bash

gem install sass
gem install sass
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7 space indent here


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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7 space indent here


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