From 85f6f00c49f4f78d93db4e47dd38384b66cd7c37 Mon Sep 17 00:00:00 2001 From: Joachim Jablon Date: Mon, 8 Jan 2024 22:43:20 +0100 Subject: [PATCH] Doc with Furo --- CHANGELOG.rst | 2 +- CONTRIBUTING.rst | 15 ------- docs/conf.py | 45 ++++++++++---------- docs/discussions.rst | 2 +- docs/favicon.ico | Bin 0 -> 15406 bytes docs/howto/async.rst | 42 ------------------- docs/howto_index.rst | 28 +++++++++---- docs/index.rst | 2 +- docs/quickstart.rst | 7 ---- docs/spelling_wordlist.txt | 47 --------------------- poetry.lock | 83 ++++++++++++++++++++++++++++++++++++- pyproject.toml | 6 ++- 12 files changed, 130 insertions(+), 149 deletions(-) create mode 100644 docs/favicon.ico delete mode 100644 docs/howto/async.rst delete mode 100644 docs/spelling_wordlist.txt diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 1f65feddf..0363e9d37 100644 --- a/CHANGELOG.rst +++ b/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/ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0d61d27fe..be21a984d 100644 --- a/CONTRIBUTING.rst +++ b/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`` diff --git a/docs/conf.py b/docs/conf.py index ebc456668..5298d088d 100644 --- a/docs/conf.py +++ b/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") diff --git a/docs/discussions.rst b/docs/discussions.rst index 5131714ed..5ecedba4d 100644 --- a/docs/discussions.rst +++ b/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: diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..e392f20075e8cc23035848eb24d6661c52c692ba GIT binary patch literal 15406 zcmeHOS&tP(6mFsq$~q`0CPs%v7=%HPRdAUg3L=Rt$`;mP8+H+a0K)(RBM5_lfV12s z@t=?=34a8tE*hRN_+oj!uBz_p?&@vs+!<6RsdV33&iT$#r|MMKIL;vFIj649p=Z6* z^1S2BaU7?A?xX3{p%^RwoGxLhrw7Fn|J$Yy zH;xny`4jL{+)30Ecoa*2JSdb{tK`jEZ9LsN<##fU8FUl)yZTMRP%2BGDg44nZuTIS zzoz5yBVW~Z?o;W6+Jp55RwaXt2XtOmI+r@Gh={C;U!{HnB)q zuIje#Gx^cGhu8ND$Qhw;>Iv^LwphBBi5DnNBUXE*UcRG#!aVR-@`q{W{cXX}LTlZe z#Y_xQ{D;t*Gj0wObC)o&Y`wpJ6o4Tkzf@hgbd+9Qn^wdyTKggYSmK?|$BsqwEh7dP zb^<-q7tMFgYs5t2PqMrGT|Fh>2+?+FSahrLNFIb4eQ0d3p6Upn%U{bMrf>YVjny(l zo+Yg({gk{S{RkKM!{4&$-=|~7B%5A+UQvC@{<3}q?U!KxVYCN>|Bau^#8lcpe7u5* zUF4&;yNrE=83QbO_j&p_)9OY{toZYfaJX|(%|pD8p29@SAp?VTE|4q+9;>a4b`z7d zf5qK5Ato$Y&BQ#~6OU;O#)qwYgSHIwNVY*#AG&|Q{|wn+-%Y!@KwKD1`WQ}r(n0$@ zAA8WQE7x}?T6tD3zqpZ`~6JahA^4?t2F*G@$cM4xgQ7rS)cg)wZEA-@UG{j`|k2o zmg{!L$K{`zUk9(*rb){QW2m%lCktGR+4V#Y!_53o*c+aK?L z+Fz2NQQYur=+=yX;Ct#E7w<0eeQylqcDFkve=SFN4uW^E&hQ6w{*!-hZed~$*%P@Q z_z$Hg=KQNvhEpt*>$24S$Oa~`UrChBr0?2Y+rz+M)FbZ(-=s2(V)FvZ$!xi(oWIa# zSf`qwddAGf14p?)?&+0n@_o%VCN@(p{_ROFZvLDivmuYK8{!+`sWEAt*q&iIs84{7 zordQNfxb5SmO9U73N!uo=s~tn{0RCM=oy$jS`}gDe9?TAH?cmQ!eJeQ3Vn->BE;D`-RRS18^0^3SmRw(**FxG(D6It#`qori8;odXl5 zlch4hAI`^YJT!m*nZY(ne;89NBgg0WHSf4{f&WWA&PnKq*4aWO>70a`opSk6UAfFR zlAZ2S?*6AacYJ%;eZ9Zh<(vYx$~}rn&E?aNaNO*4b&0{nBD)3L5{nTJJpah&OSP7X zWcdr2q4%EBgEjaa$1^&|YH0_lyDU6i%w&f`k^L5jy|(q$+mvLuM@9KfUcK7TSOggssW2SKdd6RXWB@P96 z=D>8}2QJ#qv*gn5w_oZ=#u~s8kTI(NYVFoTxf#B-CFL!;O`osMr(7ow##;8h_7fNN zv$EmWa?GSWv@bAKt9xL${391LDQ|s!1{26jHAXyNT^B(RI$3KfW!DfBf8v z*ms1x1?OXjPjGRX?$}_>C}*{C4*9E{KVkfcrMSzZ3)X^B^!)_)V&0+HwEqYbT|H^> z)Yn(F_|j|;#&51=aqp8BFj^n-$&rR5Z@bn@cKrSsKID37G7}qHINh_!Zi~DaQ~Q%Y zhw)FEk8^G+XBeITGSR%Bz5}kL{RG{Q3fludw)>lbUGKv9Aqvz`ToW) z*T~-B$G0^TKVne(<$nkMPPz*+`_rKRWB%&zvc7%&J%p^QHb&X^uzB=P=Y3-5L0Wr5 zIWz7z&{<}U{l9nkff@TX+=*_XwN|cQ{(TwjBlWYd|)iuX!`+1`-vR7qjfKSZp*f;=cT}pn1Orx zNdUZ&WNzSEkRdsejbYnlszJ5cGk(s1W(?CiF|N6+QzyD1C-1Eo21`MP=p3ZMz*?d@Gf81~S%VKXG%QN&<-%s!4#;;?%m%o?x3uo`a5(t<*}L` sections. - - -.. toctree:: - :maxdepth: 2 - - howto_index - discussions diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt deleted file mode 100644 index c5221a447..000000000 --- a/docs/spelling_wordlist.txt +++ /dev/null @@ -1,47 +0,0 @@ -app -async -asynchronicity -attrs -autogenerated -backend -backoff -builtin -Changelog -codebase -codebases -coroutine -coroutines -cron -crons -datetime -deferrer -deserialize -deserializing -Dramatiq -enqueued -executables -formatters -GitHub -Godwin -healthcheck -healthchecks -linter -linters -linting -localhost -middleware -namespaces -pre -programmatically -pycharm -PyPI -queueing -quickstart -readme -reimplement -schemas -suboptimal -sync -th -tox -uppercased diff --git a/poetry.lock b/poetry.lock index 934f09274..2652f0c4f 100644 --- a/poetry.lock +++ b/poetry.lock @@ -143,6 +143,24 @@ files = [ [package.extras] tzdata = ["tzdata"] +[[package]] +name = "beautifulsoup4" +version = "4.12.2" +description = "Screen-scraping library" +optional = false +python-versions = ">=3.6.0" +files = [ + {file = "beautifulsoup4-4.12.2-py3-none-any.whl", hash = "sha256:bd2520ca0d9d7d12694a53d44ac482d181b4ec1888909b035a3dbf40d0f57d4a"}, + {file = "beautifulsoup4-4.12.2.tar.gz", hash = "sha256:492bbc69dca35d12daac71c4db1bfff0c876c00ef4a2ffacce226d4638eb72da"}, +] + +[package.dependencies] +soupsieve = ">1.2" + +[package.extras] +html5lib = ["html5lib"] +lxml = ["lxml"] + [[package]] name = "black" version = "23.11.0" @@ -493,6 +511,23 @@ mccabe = ">=0.7.0,<0.8.0" pycodestyle = ">=2.9.0,<2.10.0" pyflakes = ">=2.5.0,<2.6.0" +[[package]] +name = "furo" +version = "2023.9.10" +description = "A clean customisable Sphinx documentation theme." +optional = false +python-versions = ">=3.8" +files = [ + {file = "furo-2023.9.10-py3-none-any.whl", hash = "sha256:513092538537dc5c596691da06e3c370714ec99bc438680edc1debffb73e5bfc"}, + {file = "furo-2023.9.10.tar.gz", hash = "sha256:5707530a476d2a63b8cad83b4f961f3739a69f4b058bcf38a03a39fa537195b2"}, +] + +[package.dependencies] +beautifulsoup4 = "*" +pygments = ">=2.7" +sphinx = ">=6.0,<8.0" +sphinx-basic-ng = "*" + [[package]] name = "greenlet" version = "3.0.2" @@ -1294,6 +1329,17 @@ files = [ {file = "snowballstemmer-2.2.0.tar.gz", hash = "sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1"}, ] +[[package]] +name = "soupsieve" +version = "2.5" +description = "A modern CSS selector implementation for Beautiful Soup." +optional = false +python-versions = ">=3.8" +files = [ + {file = "soupsieve-2.5-py3-none-any.whl", hash = "sha256:eaa337ff55a1579b6549dc679565eac1e3d000563bcb1c8ab0d0fefbc0c2cdc7"}, + {file = "soupsieve-2.5.tar.gz", hash = "sha256:5663d5a7b3bfaeee0bc4372e7fc48f9cff4940b3eec54a6451cc5299f1097690"}, +] + [[package]] name = "sphinx" version = "7.1.2" @@ -1348,6 +1394,41 @@ docs = ["furo (>=2023.7.26)", "sphinx (>=7.1.2)"] numpy = ["nptyping (>=2.5)"] testing = ["covdefaults (>=2.3)", "coverage (>=7.3)", "diff-cover (>=7.7)", "pytest (>=7.4)", "pytest-cov (>=4.1)", "sphobjinv (>=2.3.1)", "typing-extensions (>=4.7.1)"] +[[package]] +name = "sphinx-basic-ng" +version = "1.0.0b2" +description = "A modern skeleton for Sphinx themes." +optional = false +python-versions = ">=3.7" +files = [ + {file = "sphinx_basic_ng-1.0.0b2-py3-none-any.whl", hash = "sha256:eb09aedbabfb650607e9b4b68c9d240b90b1e1be221d6ad71d61c52e29f7932b"}, + {file = "sphinx_basic_ng-1.0.0b2.tar.gz", hash = "sha256:9ec55a47c90c8c002b5960c57492ec3021f5193cb26cebc2dc4ea226848651c9"}, +] + +[package.dependencies] +sphinx = ">=4.0" + +[package.extras] +docs = ["furo", "ipython", "myst-parser", "sphinx-copybutton", "sphinx-inline-tabs"] + +[[package]] +name = "sphinx-copybutton" +version = "0.5.2" +description = "Add a copy button to each of your code cells." +optional = false +python-versions = ">=3.7" +files = [ + {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"}, + {file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"}, +] + +[package.dependencies] +sphinx = ">=1.8" + +[package.extras] +code-style = ["pre-commit (==2.12.1)"] +rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"] + [[package]] name = "sphinx-github-changelog" version = "1.2.1" @@ -1709,4 +1790,4 @@ sqlalchemy = ["sqlalchemy"] [metadata] lock-version = "2.0" python-versions = "^3.8" -content-hash = "64189612e4f53390aec80c78479cbdfc7cde06a0419d07c9f297c9ba371d919d" +content-hash = "52a263a90b599a8f450a4e12d2d5c1f24c4a63f2bcdcc8b88748116e44da0be9" diff --git a/pyproject.toml b/pyproject.toml index 6ce89a21d..a70d243be 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,11 +67,13 @@ types-psycopg2 = "*" types-python-dateutil = "*" [tool.poetry.group.docs.dependencies] +django = ">=2.2" +furo = "*" Sphinx = "*" -sphinx-github-changelog = "*" sphinx-autodoc-typehints = "*" +sphinx-copybutton = "*" +sphinx-github-changelog = "*" sphinxcontrib-programoutput = "*" -django = ">=2.2" [build-system] requires = ["poetry-core>=1.0.0"]