From 93e6fe24bcbaa21a913a8c67d5f48c0e9b7185f3 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Sat, 17 Jun 2017 20:42:04 +0200 Subject: [PATCH 1/2] Finalized #418 (#433) 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 --- README.rst | 71 ++++++++++++++++++++++++++---------------------------- 1 file changed, 34 insertions(+), 37 deletions(-) diff --git a/README.rst b/README.rst index d45d0af3..a560de28 100644 --- a/README.rst +++ b/README.rst @@ -36,16 +36,14 @@ 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 @@ -53,7 +51,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 @@ -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 @@ -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 @@ -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 ------ @@ -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. @@ -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: @@ -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 -------------------------- @@ -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 `_, 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 `_, 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 ==== From 1dc21dbfd3290ce95fd430471345328e8d712819 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Sun, 18 Jun 2017 00:05:41 +0200 Subject: [PATCH 2/2] Add missing dependency in dev setup: sphinxcontrib-httpdomain (#431) --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index a560de28..cc7a1779 100644 --- a/README.rst +++ b/README.rst @@ -217,8 +217,8 @@ Set up your environment #. Install sphinx_ into a virtual environment. .. code:: bash - - pip install sphinx + + pip install sphinx sphinxcontrib-httpdomain #. Install sass.