Merge pull request #862 from ix5/docs-snapshots-style-configs

docs: Document snapshots, add "New in version x", def.-list styling, better config options documentation
isso-comments · May 5, 2022 · ede2fff · ede2fff
2 parents 0701ff2 + 25d835f
commit ede2fff
Show file tree

Hide file tree

Showing 9 changed files with 425 additions and 170 deletions.
diff --git a/docs/_static/css/site.css b/docs/_static/css/site.css
@@ -28,7 +28,7 @@ body {
 .push, .footer {
   height: 2em; }
   .push a, .push a:visited, .footer a, .footer a:visited {
-    color: #00aac2;
+    color: #2980b9;
     text-decoration: none; }
 
 .header {
@@ -231,15 +231,15 @@ main {
     main .sidebar:last-child {
       margin-right: 0; }
     main .sidebar strong {
-      color: #00aac2;
+      color: #2980b9;
       font-weight: bold;
       text-transform: uppercase;
       letter-spacing: 0.5px; }
     main .sidebar ul {
       margin-top: 0.5em;
       margin-bottom: 1em; }
-    main .sidebar ul:last-child {
-      margin-bottom: 0; }
+      main .sidebar ul:last-child {
+        margin-bottom: 0; }
     main .sidebar li {
       border-left: solid 2px #d3d3d3;
       margin-left: 0.25em;
@@ -251,15 +251,15 @@ main {
       main .sidebar li a {
         color: #2f2f2f; }
     main .sidebar .current {
-      border-left-color: #00aac2; }
+      border-left-color: #2980b9; }
       main .sidebar .current a.current {
-        color: #00aac2;
+        color: #2980b9;
         font-weight: bold; }
     main .sidebar #searchbox {
       color: #2f2f2f;
       margin: 0 0 1.4em; }
       main .sidebar #searchbox h2 {
-        color: #00aac2;
+        color: #2980b9;
         font-weight: bold;
         text-transform: uppercase;
         font-size: 14px; }
@@ -318,6 +318,17 @@ main {
         margin-right: 2em; }
         main .docs ul li > ul {
           margin: 0; }
+    main .docs table.hlist * {
+      vertical-align: top; }
+    main .docs .versionadded,
+    main .docs .versionchanged,
+    main .docs .deprecated {
+      margin: 0.3em 0; }
+      main .docs .versionadded span,
+      main .docs .versionchanged span,
+      main .docs .deprecated span {
+        background: lightyellow;
+        font-style: italic; }
   main .vcs-edit {
     font-size: 1.16em;
     line-height: 1.16em;
@@ -329,16 +340,24 @@ main {
       vertical-align: top; }
   main a {
     text-decoration: none;
-    color: #00aac2; }
+    color: #2980b9; }
   main dt {
+    font-family: Monaco, Menlo, Consolas, monospace;
     font-weight: bold;
-    margin: 1.4em 0 0.4em;
     font-size: 16px;
-    line-height: 1.4em; }
-  main dt code {
-    font-size: 16px; }
+    line-height: 1.4em;
+    display: inline-block;
+    margin: 1.4em 0 0.4em;
+    padding: 3px 6px;
+    background: #e7f2fa;
+    color: #2f2f2f;
+    border-top: 2px solid #a4cfeb; }
   main dd {
     margin-left: 1.2em; }
+    main dd dl.simple dt {
+      border-top: none;
+      background: inherit;
+      color: inherit; }
   main dl {
     margin-bottom: 0.4em; }
 
@@ -384,7 +403,7 @@ main {
       float: left;
       width: 1.4rem;
       height: 1.4rem;
-      font-family: monospace;
+      font-family: Monaco, Menlo, Consolas, monospace;
       font-size: 1.3rem;
       border-radius: 999px;
       text-align: center;

diff --git a/docs/_static/css/site.scss b/docs/_static/css/site.scss
@@ -4,11 +4,16 @@
 // Override bourbon _grid.scss
 $max-width: em(1280); // Max-width of the outer container, divided by 16
 
-$blue: #00aac2;
+$blue: #2980b9;
+$strong-blue: #6ab0de;
+$background-blue: #e7f2fa;
 $text: #2f2f2f;
 $muted-grey: #151515;
 $admon-todo: #f0b37e;
 $highlighted: #f1c40f;
+$versionchanged: lightyellow;
+
+$monospace: Monaco, Menlo, Consolas, monospace;
 
 * {
   margin: 0;
@@ -259,10 +264,10 @@ main {
     ul {
       margin-top: 0.5em;
       margin-bottom: 1em;
-    }
 
-    ul:last-child {
-      margin-bottom: 0;
+      &:last-child {
+        margin-bottom: 0;
+      }
     }
 
     li {
@@ -335,7 +340,7 @@ main {
 
     pre, code {
       font-size: 14px;
-      font-family: Monaco, Menlo, Consolas, monospace;
+      font-family: $monospace;
     }
 
     code {
@@ -390,6 +395,23 @@ main {
         }
       }
     }
+
+    // For `.. hlist::` directive, do not vertically center columns:
+    table.hlist * {
+        vertical-align: top;
+    }
+
+    .versionadded,
+    .versionchanged,
+    .deprecated {
+
+        margin: 0.3em 0;
+
+        span {
+            background: $versionchanged;
+            font-style: italic;
+        }
+    }
   }
 
   // "Edit on Github" link
@@ -411,18 +433,29 @@ main {
   }
 
   dt {
+    font-family: $monospace;
     font-weight: bold;
-    margin: 1.4em 0 0.4em;
     font-size: 16px;
     line-height: 1.4em;
-  }
-  dt code {
-    font-size: 16px;
+    display: inline-block;
+    margin: 1.4em 0 0.4em;
+    padding: 3px 6px;
+
+    background: $background-blue;
+    color: $text;
+
+    border-top: 2px solid lighten($strong-blue, 14);
   }
   dd {
     margin-left: 1.2em;
-  }
 
+    // Nested definitions should not have blue styling
+    & dl.simple dt {
+      border-top: none;
+      background: inherit;
+      color: inherit;
+    }
+  }
   dl {
     margin-bottom: 0.4em;
   }
@@ -493,7 +526,7 @@ main {
       float: left;
       width: 1.4rem;
       height: 1.4rem;
-      font-family: monospace;
+      font-family: $monospace;
       font-size: 1.3rem;
       border-radius: 999px;
       text-align: center;

diff --git a/docs/docs/contributing/documentation.rst b/docs/docs/contributing/documentation.rst
@@ -154,6 +154,9 @@ Syntax standards
   (maybe also ``error``?). See `docutils: Admonitions`__.
 - Try to keep line length under 80 characters, but don't worry when going over
   that limit when using links or code blocks
+- Use ``.. versionadded::``, ``.. versionchanged::`` and ``.. deprecated::`` to
+  make it clear to readers which version of Isso are affected by an
+  option or behavior
 
 .. __: https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html
 .. __: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
@@ -174,6 +177,9 @@ Help
 Helpful links:
 
 - `Cross-referencing with Sphinx <https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_
+- `Sphinx directives <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
+- For theme authors: Look at
+  `sphinx-rtd-theme internals <https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html>`_
 
 Debugging cross-references:
 

diff --git a/docs/docs/contributing/index.rst b/docs/docs/contributing/index.rst
@@ -142,7 +142,9 @@ What is currently needed?
 - Look at `open issues with label "good-first-issue"`__
 - Look at `open issues with label "needs-decision"`__ and chime in with your
   well thought-out opinion
-- Look at `milestones`__
+- Look at `milestones`__ - the next release of Isso will be version 0.13, and
+  you can help by looking for open issues and PRs that
+  `contribute to 0.13 <https://github.com/posativ/isso/milestone/5>`_
 - Nicer automated testing, via docker or GH actions, of most of the available
   setup options (fastcgi/proxy configs, docker, apachge/nginx, ...)
 
@@ -184,53 +186,65 @@ It is built using many different technologies and moving parts
 
 Below is a non-exhaustive list of tools, services, dependencies and
 technologies Isso's contributors and maintainers need to at least peripherally
-be aware of - that's a lot to demand of someone!
-
-Docs
-    - apiDoc
-    - sphinx with reST syntax
-
-Python
-    - Pallets project: werkzeug, jinja2, flask
-    - misaka (and changing config opts)
-    - bleach, html5lib
-    - different python versions, OS versions
-    - flake8
-    - setuptools, pip
-    - python package index (pypa) uploading
-
-Python testing
-    - pytest (unit testing)
-    - coverage
-
-Convenience tools
-    - docker
-    - vagrant
-    - ansible
-
-Javascript
-    - nodejs
-    - npm
-    - package.json oddities
-    - webpack
-    - Jest
-    - puppeteer
-    - Browser compatibility and ES5/ES6 standards
-
-Development tools
-    - make
-    - Github Actions
-
-Deployment options
-    - ``isso run [opts]``
-    - Apache (``mod_wsgi``)
-    - Apache (``mod_fastcgi``)
-    - Apache (proxy)
-    - nginx (proxy)
-    - uwswgi
-    - gunicorn
-    - gevent
-
-Importers
-    - Current disqus export format
-    - Current and past Wordpress export formats
+be aware of - that's a lot to demand of someone! Your aim should be to reduce
+this complexity, not add to it.
+
+.. hlist::
+   :columns: 2
+
+   * **Docs**
+
+     -  apiDoc
+     -  sphinx with reST syntax
+
+   * **Python**
+
+     -  Pallets project: werkzeug, jinja2, flask
+     -  misaka (and changing config opts)
+     -  bleach, html5lib
+     -  Different python versions, OS versions
+     -  setuptools, pip
+     -  Python Package Index (PyPI) uploading
+
+   * **Python testing**
+
+     -  pytest (unit testing)
+     -  coverage
+     -  flake8
+
+   * **Convenience tools**
+
+     -  Docker
+     -  Vagrant
+     -  Ansible
+
+   * **Javascript**
+
+     -  Node.js
+     -  npm
+     -  package.json oddities
+     -  webpack
+     -  Jest
+     -  puppeteer
+     -  Browser compatibility and ES5/ES6 standards
+
+   * **Development tools**
+
+     -  make
+     -  Github Actions
+
+   * **Deployment options**
+
+     -  ``isso run [opts]``
+     -  Apache (``mod_wsgi``)
+     -  Apache (``mod_fastcgi``)
+     -  Apache (proxy)
+     -  nginx (proxy)
+     -  uwswgi
+     -  gunicorn
+     -  gevent
+
+   * **Importers**
+
+     -  Current disqus export format
+     -  Current and past Wordpress export formats