[docs] Reduce width; code highlighting changes, installation guide improvements, prompt blocks

docs/_isso/layout.html

@@ -91,7 +91,6 @@ <h2>a commenting server similar to Disqus</h2>
             </header>
             <nav>
                 <a href="{{ pathto('docs') }}">Documentation</a>
-                <a href="{{ pathto('news') }}">News</a>
                 <a href="{{ pathto('docs/contributing') }}">Contribute</a>
                 <a href="{{ pathto('community') }}">community</a>
             </nav>

docs/_static/css/site.css

@@ -33,7 +33,7 @@ body {
 
 .header {
   *zoom: 1;
-  max-width: 80em;
+  max-width: 70em;
   margin-left: auto;
   margin-right: auto;
   padding-top: 1em;
@@ -87,7 +87,7 @@ body {
   box-shadow: inset 0 0 0.5em #c0c0c0; }
   .outer header {
     *zoom: 1;
-    max-width: 80em;
+    max-width: 70em;
     margin-left: auto;
     margin-right: auto;
     padding: 1em 0; }
@@ -105,7 +105,7 @@ body {
       letter-spacing: 0.05em; }
   .outer footer {
     *zoom: 1;
-    max-width: 80em;
+    max-width: 70em;
     margin-left: auto;
     margin-right: auto; }
     .outer footer:before, .outer footer:after {
@@ -115,7 +115,7 @@ body {
       clear: both; }
   .outer .index {
     *zoom: 1;
-    max-width: 80em;
+    max-width: 70em;
     margin-left: auto;
     margin-right: auto;
     padding: 1em; }
@@ -162,7 +162,7 @@ body {
 
 main {
   *zoom: 1;
-  max-width: 80em;
+  max-width: 70em;
   margin-left: auto;
   margin-right: auto;
   margin-top: 1.6em;
@@ -295,11 +295,22 @@ main {
     main .docs .highlight {
       margin: 1.2em 0;
       padding: 10px 15px;
-      background-color: #eeeeee;
-      color: #4d4d4c;
-      border: 1px solid #dddddd;
+      background-color: #f3f3f3;
+      color: #2f2f2f;
+      border: 1px solid #d3d3d3;
       border-radius: 4px;
       overflow: auto; }
+      main .docs .highlight .gp {
+        /* gp: Generic.Prompt */
+        user-select: none;
+        -webkit-user-select: text;
+        /* Safari fallback only */
+        -webkit-user-select: none;
+        /* Chrome/Safari */
+        -moz-user-select: none;
+        /* Firefox */
+        -ms-user-select: none;
+        /* IE10+ */ }
     main .docs .headerlink {
       visibility: hidden; }
     main .docs p + p {

docs/_static/css/site.scss

@@ -2,13 +2,18 @@
 @import "neat/neat";
 
 // Override bourbon _grid.scss
-$max-width: em(1280); // Max-width of the outer container, divided by 16
+$max-width: em(1120); // Max-width of the outer container, divided by 16
 
 $blue: #2980b9;
 $strong-blue: #6ab0de;
 $background-blue: #e7f2fa;
 $text: #2f2f2f;
 $muted-grey: #151515;
+
+$code-background-color: #eeeeee;
+$code-block-background-color: #f3f3f3;
+$code-block-border-color: #d3d3d3;
+
 $admon-todo: #f0b37e;
 $highlighted: #f1c40f;
 $versionchanged: lightyellow;
@@ -345,20 +350,30 @@ main {
 
     code {
       color: #002e40;
-      background-color: #eeeeee;
+      background-color: $code-background-color;
       padding: 0.2em 0.3em;
     }
 
     .highlight {
       margin: 1.2em 0;
       padding: 10px 15px;
 
-      background-color: rgb(238, 238, 238);
-      color: rgb(77, 77, 76);
+      background-color: $code-block-background-color;
+      color: $text;
 
-      border: 1px solid rgb(221, 221, 221);
+      border: 1px solid $code-block-border-color;
       border-radius: 4px;
       overflow: auto;
+
+      // Make '$' at beginning of bash code blocks non-selectable
+      // See sphinx-rtd-theme: basic.css_t
+      .gp {  /* gp: Generic.Prompt */
+         user-select: none;
+         -webkit-user-select: text; /* Safari fallback only */
+         -webkit-user-select: none; /* Chrome/Safari */
+         -moz-user-select: none; /* Firefox */
+         -ms-user-select: none; /* IE10+ */
+      }
     }
 
     .headerlink {

docs/conf.py

@@ -98,7 +98,8 @@
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'trac'
+# See https://pygments.org/styles/
+pygments_style = 'abap'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []

docs/docs/contributing/documentation.rst

@@ -31,7 +31,7 @@ You will need to have the latest version of the ``Sphinx`` documentation generat
 
 Install via pip:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ virtualenv .venv && $ source .venv/bin/activate
    (.venv) $ pip install sphinx
@@ -40,7 +40,7 @@ Install via pip:
 
 Build the docs:
 
-.. code-block:: bash
+.. code-block:: console
 
    (.venv) $ make site
 
@@ -51,7 +51,7 @@ If you have made any changes to the stylesheets, you need to install the
 `sassc`__ program and then re-generate the CSS file at
 ``docs/_static/css/site.css``:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ apt install sassc
    $ make css
@@ -130,7 +130,7 @@ Use ``.. code-block:: <language>`` and indent the code by one level:
 
 .. code-block:: rst
 
-   .. code-block:: bash
+   .. code-block:: console
 
         $ sudo apt install python3 python3-pip python3-virtualenv
         $ virtualenv .venv
@@ -144,12 +144,14 @@ Syntax standards
   ``===`` for page title, ``---`` for section headings (h3), ``^^^`` for
   sub-headings (h4).
 - Use ``$ /usr/bin/command`` to refer to shell commands and use
-  ``code-block:: bash`` over ``sh``
+  ``code-block:: console`` over ``bash`` or ``sh``.
+  For actual shell scripts, use ``sh``.
 - Use ``(.venv) $ python [cmd]`` for things that need to be run inside a
   virtual environment and be consistent
   (see `Sphinx: Narrative Documentation`__)
-- Use ``/path/to/isso/<thing>`` to refer to items inside Isso's main directory
-  and use ``comments.db`` as the name for the database
+- Use ``/path/to/isso/<thing>`` to refer to items inside Isso's installation
+  directory or for user data and use ``comments.db`` as the name for the
+  database
 - Admonitions should only be: ``note``, ``tip``, ``warning``, ``attention``,
   (maybe also ``error``?). See `docutils: Admonitions`__.
 - Try to keep line length under 80 characters, but don't worry when going over

docs/docs/guides/quickstart.rst

@@ -12,8 +12,8 @@ covered:
 Configuration
 -------------
 
-You must provide a custom configuration to set `dbpath` (your database
-location) and `host` (a list of websites for CORS_). All other options have
+You must provide a custom configuration to set ``dbpath`` (your database
+location) and ``host`` (a list of websites for CORS_). All other options have
 sane defaults.
 
 .. code-block:: ini
@@ -76,9 +76,9 @@ Try to repair the file using ``xmllint`` before you continue with the import.
 
 Now import the XML dump:
 
-.. code-block:: sh
+.. code-block:: console
 
-    ~> isso -c /path/to/isso.cfg import -t [disqus|wordpress] disqus-or-wordpress.xml
+    (.venv) $ isso -c /path/to/isso.cfg import -t [disqus|wordpress] disqus-or-wordpress.xml
     [100%]  53 threads, 192 comments
 
 .. _Disqus: https://disqus.com/
@@ -89,9 +89,9 @@ Running Isso
 
 To run Isso, simply execute:
 
-.. code-block:: sh
+.. code-block:: console
 
-    $ isso -c /path/to/isso.cfg run
+    (.venv) $ isso -c /path/to/isso.cfg run
     2013-11-25 15:31:34,773 INFO: connected to HTTP server
 
 Next, we configure Nginx_ to proxy Isso. Do not run Isso on a public interface!