Miscellaneous docs fixes (#67)

* Fix time in lunar lander tutorial * Ignore results dirs * Fix GitHub Actions link in README * Fix sidebar color in code cells * Fix github link in README * Tweak README credits * Add css selection rule * Remove global toc header * Add pyribs email for author * Disable tagging for bump2version * Remove last updated date * Update deployment process * Add 404 page * Allow different URLs based on readthedocs env * Correct readthedocs version in url * Change OpenGraph image filename * Customize ReadTheDocs flyout * Remove OpenGraph description as it is blank * Use just 1 emitter in Fooling MNIST * Update history for 0.2.1 * Bump version: 0.2.0 → 0.2.1
icaros-usc · Jan 30, 2021 · 866f320 · 866f320
1 parent 73d17cf
commit 866f320
Show file tree

Hide file tree

Showing 14 changed files with 357 additions and 276 deletions.
diff --git a/.gitignore b/.gitignore
@@ -120,6 +120,7 @@ dask-worker-space/
 !docs/_static/**/*
 !examples/tutorials/_static/**/*
 !readme_assets/*
+results/
 
 # Editor, IDE, and OS settings
 .vscode/

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -204,36 +204,28 @@ their source is shown in the docs. To create an example:
 
 ### Deploying
 
-Our deployment process is based on the process described in
-[Trunk-based development](https://trunkbaseddevelopment.com/branch-for-release/).
-
-#### Minor Release
-
-Minor versions of ribs are released from a branch off of master.
-
 1. Create a PR into master where you:
-   1. Update the version with
+   1. Update the version with `bump2version` by running the following for minor
+      versions,
       ```bash
       bump2version minor
       ```
+      or the following for patch versions:
+      ```bash
+      bump2version patch
+      ```
    1. Add all necessary info on the version to `HISTORY.md`.
-1. Once this PR is merged, create a branch off of it called
-   `releases/<version>`, e.g. `releases/0.2.0`.
-1. GitHub Actions should now automatically test and deploy this branch. Check
-   that it shows up on PyPI.
-
-#### Patch Release
-
-Patch releases (e.g. `0.2.1`) are released from their corresponding minor
-branch.
-
-1. Checkout the relevant minor branch, and cherry-pick any necessary bug fixes
-   from master branch.
-1. Create a PR into master where you update `HISTORY.md` with info about the
-   release. Once this PR is merged, cherry-pick it onto the minor branch.
-1. On the minor branch, update the version with:
+2. Once the PR has passed CI/CD and been squashed-and-merged into master,
+   locally tag the squash commit with a tag like `v0.2.1`, e.g.
    ```bash
-   bump2version patch
+   git tag v0.2.1 HEAD
    ```
-1. Push the minor branch updates. GitHub Actions should now automatically test
-   and deploy the branch. Check that it shows up on PyPI.
+3. Push the tag with
+   ```bash
+   git push --tags
+   ```
+4. Check that the version was deployed to PyPI. If it failed, delete the tag
+   make appropriate fixes, and repeat steps 2 and 3.
+5. Write up the release on GitHub.
+
+Our deployment process may change in the future as pyribs becomes more complex.
diff --git a/HISTORY.md b/HISTORY.md
@@ -4,6 +4,11 @@
 
 - Alpha release
 
+### 0.2.1 (2021-01-29)
+
+- Package metadata fixes (author, email, url)
+- Miscellaneous documentation improvements
+
 ## 0.1.0 (2020-09-11)
 
 - Test release

diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # pyribs
 
-|                     Source                     |                                                       PyPI                                                        |                                                                                                                  CI/CD                                                                                                                   |                    Docs                    |                                                                   Docs Status                                                                    |
-| :--------------------------------------------: | :---------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: |
-| [GitHub](https://github.com/icaros-usc/pyribs) | [![PyPI](https://img.shields.io/pypi/v/ribs.svg?style=flat-square&color=blue)](https://pypi.python.org/pypi/ribs) | [![Automated Testing](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Ficaros-usc%2Fpyribs%2Fbadge&style=flat-square)](https://github.com/icaros-usc/pyribs/actions?query=workflow%3A"Automated+Testing") | [docs.pyribs.org](https://docs.pyribs.org) | [![Documentation Status](https://readthedocs.org/projects/ribs/badge/?version=latest&style=flat-square)](https://readthedocs.org/projects/ribs/) |
+|                     Source                     |                                                       PyPI                                                        |                                                                                                      CI/CD                                                                                                       |                    Docs                    |                                                                   Docs Status                                                                    |
+| :--------------------------------------------: | :---------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: |
+| [GitHub](https://github.com/icaros-usc/pyribs) | [![PyPI](https://img.shields.io/pypi/v/ribs.svg?style=flat-square&color=blue)](https://pypi.python.org/pypi/ribs) | [![Tests](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Ficaros-usc%2Fpyribs%2Fbadge&style=flat-square)](https://github.com/icaros-usc/pyribs/actions?query=workflow%3A"Tests") | [docs.pyribs.org](https://docs.pyribs.org) | [![Documentation Status](https://readthedocs.org/projects/ribs/badge/?version=latest&style=flat-square)](https://readthedocs.org/projects/ribs/) |
 
 A _bare-bones_ quality diversity optimization library. The pyribs library is the
 official implementation of the Covariance Matrix Adaptation MAP-Elites (CMA-ME)
@@ -189,7 +189,7 @@ The pyribs library is released under the
 
 ## Credits
 
-pyribs was initially created with
+The pyribs package was initially created with
 [Cookiecutter](https://github.com/audreyr/cookiecutter) and the
 [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)
 project template.
diff --git a/docs/404.md b/docs/404.md
@@ -0,0 +1,3 @@
+# 404
+
+Page Not Found
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -1,7 +1,24 @@
+/* Grey highlight for selections. */
+::selection {
+  background-color: rgba(192, 192, 192, 0.5);
+}
+::-moz-selection {
+  background-color: rgba(192, 192, 192, 0.5);
+}
+
+/* Removes the weird title at the top of the global TOC when the page is
+ * expanded. */
+@media only screen and (min-width: 77em) {
+  .md-nav__title.md-nav__title--site a {
+    font-weight: normal !important;
+    display: none;
+  }
+}
+
 /* Styles the left border of input cells in rendered Jupyter notebooks (they are
  * green by default, which does not match the theme). */
 div.cell div.cell_input {
-  border-left-color: #3f51b5 !important;
+  border-left-color: #7e57c2 !important;
 }
 
 /* Increases the visibility of classes, methods, etc. in API definitions. */
@@ -16,6 +33,17 @@ dd {
   padding-left: 15px;
 }
 
+/* Excludes the border from ReadTheDocs version menu. */
+div.rst-versions dd {
+  border-left: 0px;
+  padding-left: 0px;
+}
+
+/* Hides ReadTheDocs "On GitHub" field. */
+div.rst-versions div.rst-other-versions dl:nth-child(3) {
+  display: none;
+}
+
 /* Makes the link icons show up next to items in the API reference. */
 a.headerlink {
   opacity: 1 !important;

diff --git a/docs/_static/imgs/open_graph.png → docs/_static/imgs/open_graph_image.png b/docs/_static/imgs/open_graph.png → docs/_static/imgs/open_graph_image.png
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -16,7 +16,9 @@
   theme_base_url +
   (pagename if pagename != 'index' else '')
 }}" />
-<meta property="og:image" content="{{ theme_base_url + '_static/imgs/open_graph.png' }}" />
-<meta property="og:description" content="{{ description }}" />
+<meta property="og:image" content="{{ theme_base_url + '_static/imgs/open_graph_image.png' }}" />
+
+{# Currently, there is no description available. #}
+{# <meta property="og:description" content="{{ description }}" /> #}
 
 {%- endblock %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -29,6 +29,8 @@
 sys.path.insert(0, os.path.abspath(".."))
 
 DEV_MODE = os.environ.get("DOCS_MODE", "regular") == "dev"
+READTHEDOCS_VERSION = os.environ.get("READTHEDOCS_VERSION", "latest")
+READTHEDOCS_LANGUAGE = os.environ.get("READTHEDOCS_LANGUAGE", "en")
 
 # -- General configuration ---------------------------------------------
 
@@ -117,7 +119,8 @@
 # material theme options (see theme.conf for more information)
 html_theme_options = {
     "nav_title": "pyribs",
-    "base_url": "https://docs.pyribs.org/en/latest/",
+    "base_url": (f"https://docs.pyribs.org/{READTHEDOCS_LANGUAGE}/"
+                 f"{READTHEDOCS_VERSION}/"),
     "repo_url": "https://github.com/icaros-usc/pyribs/",
     "repo_name": "pyribs",
     "google_analytics_account": None,
@@ -133,7 +136,7 @@
     "nav_links": [{
         "href": "index",
         "internal": True,
-        "title": "pyribs"
+        "title": "Home"
     },],
     "heroes": {
         "index": "A bare-bones quality diversity optimization library."
@@ -149,7 +152,7 @@
     "table_classes": ["plain"],
 }
 
-html_last_updated_fmt = ""
+html_last_updated_fmt = None
 
 html_use_index = True
 html_domain_indices = True