Merge pull request #888 from procrastinate-org/furo

CHANGELOG.rst

@@ -4,6 +4,6 @@ Changelog
 .. See this changelog built at the following URL
 
 .. changelog::
-    :changelog-url: https://procrastinate.readthedocs.io/en/latest/changelog.html
+    :changelog-url: https://procrastinate.readthedocs.io/en/main/changelog.html
     :github: https://github.com/procrastinate-org/procrastinate/releases/
     :pypi: https://pypi.org/project/procrastinate/

CONTRIBUTING.rst

@@ -161,21 +161,6 @@ Build with:
     $ scripts/docs  # build the html doc
     $ scripts/htmldoc  # browse the doc in you browser
 
-Run spell checking on the documentation (optional):
-
-.. code-block:: console
-
-    $ sudo apt install enchant
-    $ scripts/docs-spelling
-
-Because of outdated software and version incompatibilities, spell checking is not
-checked in the CI, and we don't require people to run it in their PR. Though, it's
-always a nice thing to do. Feel free to include any spell fix in your PR, even if it's
-not related to your PR (but please put it in a dedicated commit).
-
-If you need to add words to the spell checking dictionary, it's in
-``docs/spelling_wordlist.txt``. Make sure the file is alphabetically sorted.
-
 If Sphinx's console output is localized and you would rather have it in English,
 (which make google-based debugging much easier), use the environment variable
 ``export LC_ALL=C.utf-8``

docs/conf.py

@@ -16,19 +16,18 @@
 
 import datetime
 import os
-import pathlib
-import sys
 from typing import List
 
 # -- Project information -----------------------------------------------------
 
-project = "procrastinate"
-copyright = f"{datetime.datetime.now().year}, Peopledoc"
-author = "Peopledoc"
+project = "Procrastinate"
+copyright = (
+    f"""2019-{datetime.datetime.now().year}, Joachim Jablon, Eric Lemoine, PeopleDoc"""
+)
+author = "Joachim Jablon"
 
 
 # -- General configuration ---------------------------------------------------
-sys.path.append(str(pathlib.Path("sphinxext").absolute()))
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -39,13 +38,8 @@
     "sphinx_autodoc_typehints",
     "sphinxcontrib.programoutput",
     "sphinx_github_changelog",
+    "sphinx_copybutton",
 ]
-try:
-    import sphinxcontrib.spelling  # noqa
-except ImportError:
-    pass
-else:
-    extensions.append("sphinxcontrib.spelling")
 
 set_type_checking_flag = True
 
@@ -65,16 +59,12 @@
 # https://github.com/sphinx-doc/sphinx/issues/7418
 suppress_warnings = ["ref.term"]
 
-# -- Spell check -------------------------------------------------------------
-
-spelling_word_list_filename = "spelling_wordlist.txt"
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "furo"
 
 # 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,
@@ -87,12 +77,21 @@
 master_doc = "index"
 
 html_theme_options = {
-    "description": "Python/PostgreSQL task processing library",
-    "sidebar_width": "235px",
-    "github_user": "procrastinate-org",
-    "github_repo": "procrastinate",
-    "badge_branch": "main",
-    "github_button": True,
+    "light_css_variables": {
+        "color-brand-primary": "#e8220a",
+        "color-brand-content": "#e8220a",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#ea9f9e",
+        "color-brand-content": "#ea9f9e",
+    },
+    "source_repository": "https://github.com/procrastinate-org/procrastinate/",
+    "source_branch": "main",
+    "source_directory": "docs/",
 }
 
+html_favicon = "favicon.ico"
+
+# -- Options for sphinx_github_changelog ---------------------------------
+
 sphinx_github_changelog_token = os.environ.get("CHANGELOG_GITHUB_TOKEN")

docs/discussions.rst

@@ -187,7 +187,7 @@ to parallelize (thread-safe) I/Os.
 .. _Global Interpreter Lock: https://docs.python.org/3/glossary.html#term-global-interpreter-lock
 
 Procrastinate natively supports asynchronous job deferring, and asynchronous job
-execution (see `howto/async`, `howto/concurrency`, `howto/sync_defer`).
+execution (see `howto/concurrency`, `howto/sync_defer`).
 
 .. _discussions-pool-size:
 

docs/howto_index.rst

@@ -2,35 +2,45 @@ How to...
 =========
 
 .. toctree::
-    :maxdepth: 1
+    :titlesonly:
+    :caption: Basics
 
     howto/app
     howto/connector
     howto/open_connection
     howto/tasks
     howto/defer
-    howto/context
     howto/worker
     howto/command_line
+
+.. toctree::
+    :titlesonly:
+    :caption: Advanced features
+
+    howto/context
     howto/locks
     howto/schedule
     howto/queueing_locks
-    howto/concurrency
     howto/cron
     howto/retry
     howto/middleware
     howto/events
-    howto/async
     howto/sync_defer
     howto/django
-    howto/logging
+    howto/custom_json_encoder_decoder
+    howto/blueprints
+
+.. toctree::
+    :titlesonly:
+    :caption: Going to production
+
     howto/testing
+    howto/logging
     howto/deployment
     howto/migrations
+    howto/concurrency
     howto/monitoring
-    howto/delete_finished_jobs
-    howto/retry_stalled_jobs
     howto/connections
-    howto/custom_json_encoder_decoder
     howto/schema
-    howto/blueprints
+    howto/delete_finished_jobs
+    howto/retry_stalled_jobs

docs/index.rst

@@ -2,7 +2,7 @@
   :end-before: end-of-index-doc
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    quickstart
    howto_index

docs/quickstart.rst

@@ -249,10 +249,3 @@ example, have a look at the locks feature: `howto/locks`.
 
 If you want to better understand some design decisions, head to the `Discussions
 <discussions>` sections.
-
-
-.. toctree::
-   :maxdepth: 2
-
-   howto_index
-   discussions