doc: Use read the docs theme on website (#408)

This commit updates the website theme from "sphinx_bootstrap_theme" to "sphinx_rtd_theme". It also include documentation for the command line interface and the release process.
amueller · Jul 26, 2018 · d4f14d2 · d4f14d2
1 parent b41c6a9
commit d4f14d2
Show file tree

Hide file tree

Showing 12 changed files with 95 additions and 148 deletions.
diff --git a/doc/_static/bootstrap.min.css b/doc/_static/bootstrap.min.css
diff --git a/doc/_static/main.css b/doc/_static/main.css
diff --git a/doc/_static/theme_override.css b/doc/_static/theme_override.css
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
diff --git a/doc/cli.rst b/doc/cli.rst
@@ -0,0 +1,7 @@
+Command Line Interface
+======================
+
+.. argparse::
+   :module: wordcloud.wordcloud_cli
+   :func: make_parser
+   :prog: wordcloud_cli.py
diff --git a/doc/conf.py b/doc/conf.py
@@ -14,7 +14,6 @@
 
 import sys
 import os
-import sphinx_bootstrap_theme
 
 from datetime import date
 
@@ -35,6 +34,7 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.viewcode',
+    'sphinxarg.ext',
     'numpydoc'
 ]
 
@@ -102,14 +102,10 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'bootstrap'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
-
-
-def setup(app):
-    app.add_stylesheet('theme_override.css')
+# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -130,7 +126,7 @@ def setup(app):
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -253,49 +249,4 @@ def setup(app):
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.
 html_theme_options = {
-    # Navigation bar title. (Default: ``project`` value)
-    'navbar_title': "Wordcloud",
-
-    # Tab name for entire site. (Default: "Site")
-    # 'navbar_site_name': "Site",
-
-    # A list of tuples containting pages to link to.  The value should
-    # be in the form [(name, page), ..]
-    'navbar_links': [
-        ('Examples', 'auto_examples/index'),
-        ('References', 'references'),
-    ],
-
-    # Global TOC depth for "site" navbar tab. (Default: 1)
-    # Switching to -1 shows all levels.
-    'globaltoc_depth': 0,
-
-    # Include hidden TOCs in Site navbar?
-    #
-    # Note: If this is "false", you cannot have mixed ``:hidden:`` and
-    # non-hidden ``toctree`` directives in the same page, or else the build
-    # will break.
-    #
-    # Values: "true" (default) or "false"
-    'globaltoc_includehidden': "true",
-
-    # HTML navbar class (Default: "navbar") to attach to <div> element.
-    # For black navbar, do "navbar navbar-inverse"
-    'navbar_class': "navbar",
-
-    # Fix navigation bar to top of page?
-    # Values: "true" (default) or "false"
-    'navbar_fixed_top': "true",
-
-    # Location of link to source.
-    # Options are "nav" (default), "footer" or anything else to exclude.
-    'source_link_position': "None",
-
-    # Bootswatch (http://bootswatch.com/) theme.
-    #
-    # Options are nothing with "" (default) or the name of a valid theme
-    # such as "amelia" or "cosmo".
-    #
-    # Note that this is served off CDN, so won't be available offline.
-    # 'bootswatch_theme': "united",
 }
diff --git a/doc/images/a_new_hope.png b/doc/images/a_new_hope.png
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,50 +1,33 @@
-.. raw:: html
-
-    <div class="jumbotron">
-      <div class="container">
-        <h1>More word-clouds!</h1>
-        <p>Here you find instructions on how to create wordclouds with my Python wordcloud project. With the new and revamped interface, this is easier than ever.
-        Compared to other wordclouds, my algorithm has the advantage of
-        <ul>
-            <li>filling all available space.
-            <li>being able to use arbitraty masks.
-            <li>having a stupid simple algorithm (with an efficient implementation) that can be easily modified.
-            <li>being in Python ;)
-        </ul>
-        You can see some examples below.
-        </p>
-        <p><a href="https://github.com/amueller/word_cloud" class="btn btn-primary btn-lg" role="button">Github repository</a></p>
-      </div>
-    </div>
-
-    <div class="container">
-      <!-- Example row of columns -->
-      <div class="row">
-          <div class="col-xs-3 col-md-3">
-            <a href="auto_examples/masked.html" class="thumbnail">
-              <img src="_images/sphx_glr_masked_001.png" alt="...">
-            </a>
-          </div>
-          <div class="col-xs-3 col-md-3">
-            <a href="auto_examples/colored.html" class="thumbnail">
-              <img src="_images/sphx_glr_colored_001.png" alt="...">
-            </a>
-          </div>
-          <div class="col-xs-3 col-md-3">
-            <a href="auto_examples/a_new_hope.html" class="thumbnail">
-              <img src="_images/sphx_glr_a_new_hope_001.png" alt="...">
-            </a>
-          </div>
-          <div class="col-xs-3 col-md-3">
-            <a href="auto_examples/simple.html" class="thumbnail">
-              <img src="_images/sphx_glr_simple_001.png" alt="...">
-            </a>
-          </div>
-      </div>
-     </div>
+WordCloud for Python documentation
+==================================
+
+Here you find instructions on how to create wordclouds with my Python wordcloud project. 
+Compared to other wordclouds, my algorithm has the advantage of
+
+* filling all available space.
+* being able to use arbitraty masks.
+* having a stupid simple algorithm (with an efficient implementation) that can be easily modified.
+* being in Python
+
+Check out the :ref:`example_gallery`.
+
+The code of the project is on Github: `word_cloud <https://github.com/amueller/word_cloud>`_
+
+  .. figure:: images/a_new_hope.png
+     :width: 300px
+     :target: auto_examples/a_new_hope.html
+     :align: center
 
 .. toctree::
     :hidden:
-
+    :caption: User Documentation
+
+    references
+    cli
     auto_examples/index
-    references.rst
+
+.. toctree::
+    :hidden:
+    :caption: Contributor Documentation
+
+    make_a_release
diff --git a/doc/make_a_release.rst b/doc/make_a_release.rst
@@ -0,0 +1,42 @@
+================
+Making a release
+================
+
+This document guides a contributor through creating a release of the wordcloud
+python packages.
+
+A core developer should use the following steps to create a release of
+**wordcloud**.
+
+1. Make sure that all CI tests are passing: `AppVeyor`_, `CircleCI`_ and `Travis CI`_.
+
+2. Tag the release. For version *X.Y.Z*::
+
+    release=X.Y.Z
+    git tag -s -m "wordcloud ${release}" ${release} origin/master
+
+3. Push the tag::
+
+    git push origin ${release}
+
+  .. note:: This will trigger builds on each CI services and automatically upload the wheels \
+            and source distribution on `PyPI`_.
+
+4. Check the status of the builds on `AppVeyor`_, `CircleCI`_ and `Travis CI`_.
+
+5. Once the builds are completed, check that the distributions are available on `PyPI`_.
+
+6. Finally, make sure the package can be installed::
+
+    mkvirtualenv test-install
+    pip install wordcloud
+    python -c "import wordcloud;print(wordcloud.__version__)"
+    deactivate
+    rmvirtualenv test-install
+
+
+.. _AppVeyor: https://ci.appveyor.com/project/amueller/word-cloud/history
+.. _CircleCI: https://circleci.com/gh/amueller/word_cloud
+.. _Travis CI: https://travis-ci.org/amueller/word_cloud/pull_requests
+
+.. _PyPI: https://pypi.org/project/wordcloud
diff --git a/doc/requirements-doc.txt b/doc/requirements-doc.txt
@@ -1,7 +1,8 @@
 numpydoc
 sphinx
-sphinx_bootstrap_theme
+sphinx_rtd_theme
 sphinx_gallery
+sphinx-argparse
 
 #
 # Example requirements

diff --git a/examples/README.txt b/examples/README.txt
@@ -0,0 +1,4 @@
+.. _example_gallery:
+
+Gallery of Examples
+===================
diff --git a/wordcloud/wordcloud_cli.py b/wordcloud/wordcloud_cli.py
@@ -85,8 +85,7 @@ def main(args, text, imagefile):
         image.save(imagefile, format='png', optimize=True)
 
 
-def parse_args(arguments):
-    # prog = 'python wordcloud_cli.py'
+def make_parser():
     description = ('A simple command line interface for wordcloud module.')
     parser = argparse.ArgumentParser(description=description)
     parser.add_argument(
@@ -150,6 +149,12 @@ def parse_args(arguments):
     parser.add_argument(
         '--version', action='version',
         version='%(prog)s {version}'.format(version=__version__))
+    return parser
+
+
+def parse_args(arguments):
+    # prog = 'python wordcloud_cli.py'
+    parser = make_parser()
     args = parser.parse_args(arguments)
 
     if args.colormask and args.color: