[docs] Polish contribute page, css list nits, client-config & docker fixes

Dockerfile

@@ -86,7 +86,7 @@ CMD ["/isso/bin/gunicorn", "-b", "0.0.0.0:8080", "-w", "4", "--preload", "isso.r
 # $ docker build -t isso .
 #
 # Run:
-# $ mkdir config
-# $ cp contrib/isso-dev.conf config/isso.cfg
-# $ mkdir db/
-# $ docker run -d --rm --name isso -p 8080:8080 -v $PWD/config:/config -v $PWD/db:/db isso:latest
+# $ mkdir -p config/ db/
+# $ cp contrib/isso.sample.cfg config/isso.cfg
+# Set 'dbpath' to '/db/comments.db' and adjust 'host'
+# $ docker run -d --rm --name isso -p 127.0.0.1:8080:8080 -v $PWD/config:/config -v $PWD/db:/db isso:latest

MANIFEST.in

@@ -1,14 +1,18 @@
 include isso/js/embed.min.js
 include isso/js/embed.dev.js
+include isso/js/embed.dev.js.map
 include isso/js/count.min.js
 include isso/js/count.dev.js
+include isso/js/count.dev.js.map
 include isso/js/admin.js
 
 include isso/isso.cfg
 
 include isso/templates/admin.html
 include isso/templates/disabled.html
 include isso/templates/login.html
+
 include isso/css/admin.css
 include isso/css/isso.css
+
 include isso/img/isso.svg

Makefile

@@ -82,7 +82,7 @@ apidoc-init:
 apidoc: $(ISSO_PY_SRC) $(APIDOC_SRC)
 	$(APIDOC) --config apidoc/apidoc.json \
 		--input isso/views/ --input apidoc/ \
-		--output $(APIDOC_DST)
+		--output $(APIDOC_DST) --private
 	cp -rT $(APIDOC_DST) $(DOCS_HTML_DST)/docs/api/
 
 coverage: $(ISSO_PY_SRC)

README.md

@@ -42,6 +42,12 @@ If you're stuck, follow the [Install guide](https://isso-comments.de/docs/refere
 see [Troubleshooting](https://isso-comments.de/docs/guides/troubleshooting/) and browse
 the [the full documentation](https://isso-comments.de/docs/).
 
+## Docker
+
+A Docker image with the latest stable release is provided at
+`ghcr.io/isso-comments/isso:latest`. See
+[Using Docker](https://isso-comments.de/docs/reference/installation/#using-docker).
+
 ## Contributing
 - Pull requests are very much welcome! These might be
   [good first issues](https://github.com/posativ/isso/labels/good-first-issue)

contrib/isso.sample.cfg

@@ -0,0 +1,9 @@
+# Isso example configuration file
+# vim: set filetype=dosini
+
+[general]
+
+dbpath = comments.db
+host =
+    http://localhost:80/
+# public-endpoint =

docs/_static/css/site.css

@@ -129,25 +129,26 @@ body {
       .outer .index figure img {
         max-width: 100%;
         max-height: 100%; }
-    .outer .index ul {
+    .outer .index ul, .outer .index ol {
       display: block;
       float: left;
       margin-right: 5.8515051827%;
       width: 57.6593979269%;
       margin-top: 1em; }
-      .outer .index ul:last-child {
+      .outer .index ul:last-child, .outer .index ol:last-child {
         margin-right: 0; }
-      .outer .index ul li {
-        list-style-type: none;
+      .outer .index ul li, .outer .index ol li {
         margin-bottom: 2em; }
-        .outer .index ul li strong {
+        .outer .index ul li strong, .outer .index ol li strong {
           font-weight: normal;
           font-size: 18px;
           color: black; }
-        .outer .index ul li p {
+        .outer .index ul li p, .outer .index ol li p {
           color: #2f2f2f; }
-        .outer .index ul li p + p {
+        .outer .index ul li p + p, .outer .index ol li p + p {
           margin-top: 0.5em; }
+    .outer .index ul li {
+      list-style-type: none; }
 
 .footer {
   text-align: right;
@@ -229,10 +230,10 @@ main {
       font-weight: bold;
       text-transform: uppercase;
       letter-spacing: 0.5px; }
-    main .sidebar ul {
+    main .sidebar ul, main .sidebar ol {
       margin-top: 0.5em;
       margin-bottom: 1em; }
-      main .sidebar ul:last-child {
+      main .sidebar ul:last-child, main .sidebar ol:last-child {
         margin-bottom: 0; }
     main .sidebar li {
       border-left: solid 2px #d3d3d3;
@@ -332,14 +333,18 @@ main {
       margin: 1em 0;
       border-left: 5px solid #eee;
       padding: 0 1em; }
-    main .docs ul {
+    main .docs ul, main .docs ol {
       margin: 1em 0; }
-      main .docs ul li {
-        list-style-type: square;
+      main .docs ul li, main .docs ol li {
         margin-left: 2em;
         margin-right: 2em; }
-        main .docs ul li > ul {
+        main .docs ul li > ul, main .docs ul li > ol, main .docs ol li > ul, main .docs ol li > ol {
           margin: 0; }
+    main .docs ul li {
+      list-style-type: square; }
+    main .docs ol.simple li {
+      padding-left: 0.2em;
+      margin-left: 1.8em; }
     main .docs table.hlist * {
       vertical-align: top; }
     main .docs table.docutils {

docs/_static/css/site.scss

@@ -142,12 +142,11 @@ body {
       }
     }
 
-    ul {
+    ul, ol {
       @include span-columns(3 of 5);
       margin-top: 1em;
 
       li {
-        list-style-type: none;
         margin-bottom: 2em;
 
         strong {
@@ -165,6 +164,11 @@ body {
         }
       }
     }
+    ul {
+        li {
+          list-style-type: none;
+        }
+    }
   }
 }
 
@@ -258,7 +262,7 @@ main {
       letter-spacing: 0.5px;
     }
 
-    ul {
+    ul, ol {
       margin-top: 0.5em;
       margin-bottom: 1em;
 
@@ -413,22 +417,32 @@ main {
       padding: 0 1em;
     }
 
-    ul {
+    ul, ol {
       margin: 1em 0;
 
       li {
-        list-style-type: square;
         margin-left: 2em;
         margin-right: 2em;
 
         > {
           // Nested lists shouldn't have margins
-          ul {
+          ul, ol {
               margin: 0;
           }
         }
       }
     }
+    ul {
+      li {
+        list-style-type: square;
+      }
+    }
+    ol.simple {
+      li {
+        padding-left: 0.2em;
+        margin-left: 1.8em;
+      }
+    }
 
     // For `.. hlist::` directive, do not vertically center columns:
     table.hlist * {

docs/docs/contributing/documentation.rst

@@ -7,10 +7,11 @@ configure for several use cases, and invite people to improve the project by
 participating.
 
 .. note::
-   Please contribute to these docs! *Some* documentation is better than no
-   documentation. You may look at the ``docs/`` folder to see how existing
-   documentation is written or click the top right "Edit on GitHub" button to
-   directly edit a page.
+   You may look at the `docs/`_ folder to see how existing documentation is
+   written or click the top right **"Edit on GitHub"** button to directly edit
+   a page.
+
+.. _docs/: https://github.com/posativ/isso/tree/master/docs
 
 Sections covered in this document:
 
@@ -31,7 +32,7 @@ example:
 
     One asterisk: *text* for emphasis (italics),
     Two asterisks: **text** for strong emphasis (boldface), and
-    Double backquotes: ``text`` for code samples.
+    Double backticks: ``text`` for code samples.
 
 .. __: https://www.sphinx-doc.org/en/master/
 
@@ -84,6 +85,7 @@ How to write reST
 -----------------
 First and foremost, see the
 `reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
+You can play with a live rST editor at `snippets.documatt.com <https://snippets.documatt.com/>`_.
 
 **Links:**
 
@@ -191,7 +193,8 @@ Inspiration
 The following documentation pages should serve as good examples. They are from
 related projects that also offer commenting functionality.
 
-- `Commento Documentation <https://docs.commento.io/>`_
+- `Commento Documentation <https://docs.commento.io/>`_, especially the
+  `contributing section <https://docs.commento.io/contributing/>`_.
 - `Remark42 Documentation <https://remark42.com/docs/getting-started/installation/>`_
 - `Schnack Documentation <https://schnack.cool/>`_
 

docs/docs/contributing/index.rst

@@ -1,13 +1,15 @@
 Contribute
 ==========
 
-Sections covered in this document:
+.. list-table:: **I am looking to...**
 
-.. contents::
-    :local:
+    * - ... :ref:`report an issue <contribute-report-issues>`
+      - ... :ref:`translate Isso into my language <contribute-translations>`
+      - ... :ref:`improve the documentation <contribute-docs>`
+      - ... :ref:`contribute code <contribute-code>`
 
-.. note:: In short: We welcome your changes. We don't bite and are happy for
-   anyone who donates their time and effort to the project.
+*The Isso community welcomes your changes. We don't bite and are happy for
+anyone who donates their time and effort to the project.*
 
 .. _contribute-report-issues:
 
@@ -52,13 +54,17 @@ for pluralforms_ in the templating engine.
 .. __: https://github.com/posativ/isso/blob/master/isso/js/app/i18n/
 .. _pluralforms: http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms
 
+.. _contribute-docs:
+
 Documentation
 -------------
 
 Documentation improvements are sorely needed. Anything that makes the
 experience for a newcomer more pleasant is always welcome.
 Please see the :doc:`documentation` page for more details.
 
+.. _contribute-code:
+
 Code contributions
 ------------------
 
@@ -69,27 +75,71 @@ person, you can make the lives of the maintainers a lot easier.
 These guidelines are here to help your thought process and hopefully make you
 aware of a few aspects you might not have thought about yet.
 
-.. The project author @posativ has stipulated these basic two tenets:
-.. *  no hard-wired external services (e.g. Gravatar, Akismet)
-.. *  no support for ancient browsers (e.g. IE6-9)
+.. _contribute-checklist:
 
-Submitting a change
-^^^^^^^^^^^^^^^^^^^
+.. note:: **Submitting a change**
 
-- Please, if possible, run all test suites (see
-  :doc:`/docs/technical-docs/testing`) and make sure they pass
-- If it's a user-facing feature or an important bugfix, add ``CHANGES.rst``
-  entry
-- Add yourself to ``CONTRIBUTORS.txt``, if you like
+    1. Write **proper commit messages** (see next paragraph)
+    2. If adding features: **Add or amend tests** to cover the changes
+    3. Run all **test suites** (see :doc:`/docs/technical-docs/testing`) and make
+       sure they pass
+    4. If docs changes needed: Update the :doc:`documentation <documentation>`
+       accordingly.
+    5. If it's a user-facing feature or an important bugfix, add ``CHANGES.rst``
+       entry
+    6. Add yourself to ``CONTRIBUTORS.txt``, if you like
 
-How to write commit messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _contribute-commitmsg:
 
-- Mention the affected part in the title
+How to write good commit messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Mention the affected part in the title (e.g. ``setup.py``)
 - Keep title under 50 characters if possible, at most 72
 - Keep body under 80 characters of width
 - Explain what the change does
 - Link to related issues or references
+- Ideally, how to verify that this commit does what it says
+
+The `commento docs`_ have a more extensive explanation of good commits.
+
+This is an example of a **good commit:**
+
+.. code-block::
+
+    js: Postbox: Use labels rather than placeholders
+
+    Placeholders are is meant to be a hint (an example input)
+    for the user about what to enter into the field, but
+    shouldn't be used in lieu of a <label>.
+
+    See following links for further justification:
+    - https://www.tpgi.com/html5-accessibility-chops-the-placeholder-attribute/
+    - https://www.nngroup.com/articles/form-design-placeholders/
+    - https://www.maxability.co.in/2016/01/03/placeholder-attribute-and-why-it-is-not-accessible/
+
+    This commit is a reland of
+    https://github.com/posativ/isso/pull/356 with a fix for the
+    placeholder-replacement code in `isso.js` as reported in
+    https://github.com/posativ/isso/issues/524
+
+...while this is a **bad commit:**
+
+.. code-block::
+
+    Fix classes
+
+It does not tell the reviewer which part is affected, why it is necessary or
+why this particular way of doing things was chosen.
+
+.. _commento docs: https://docs.commento.io/contributing/development-guidelines.html
+
+Considerations when submitting changes
+--------------------------------------
+
+The following sections will help you decide how to tackle larger architectural
+issues and help avoid wasted efforts for changes that are unlikely to be
+accepted.
 
 Design philosophy / Zen of Isso
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^