diff --git a/doc/conf.py b/doc/conf.py index f8a9d8fdc7..16af72f84a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -55,6 +55,7 @@ 'sphinx.ext.viewcode', # display code with line numbers and line highlighting 'sphinx_copybutton', # Adds a copy button to code blocks 'sphinx_sitemap', # sitemap.xml generation + 'doc.extensions.prettyspecialmethods', # Forker plugin for prettifying special methods ] # Add any paths that contain templates here, relative to this directory. @@ -264,19 +265,16 @@ def generate_color_table(filename, source): source[0] += append_text -def source_read_handler(_app, docname, source): +def source_read_handler(_app, doc_name: str, source): """ Event handler for source-read event. Where we can modify the source of a document before it is parsed. """ - file_path = os.path.dirname(os.path.abspath(__file__)) - os.chdir(file_path) - - # Transform source for arcade.color and arcade.csscolor - if docname == "api_docs/arcade.color": - generate_color_table("../arcade/color/__init__.py", source) - elif docname == "api_docs/arcade.csscolor": - generate_color_table("../arcade/csscolor/__init__.py", source) + # Inject the color tables into the source + if doc_name == "api_docs/arcade.color": + generate_color_table("arcade/color/__init__.py", source) + elif doc_name == "api_docs/arcade.csscolor": + generate_color_table("arcade/csscolor/__init__.py", source) def on_autodoc_process_bases(app, name, obj, options, bases): @@ -284,8 +282,6 @@ def on_autodoc_process_bases(app, name, obj, options, bases): bases[:] = [base for base in bases if base is not object] - - def setup(app): # Separate stylesheets loosely by category. app.add_css_file("css/colors.css") diff --git a/make.py b/make.py index 46fe6d4bd2..cf9d0921c6 100755 --- a/make.py +++ b/make.py @@ -31,18 +31,18 @@ def _resolve(p: PathLike, strict: bool = False) -> Path: # General sphinx state / options -SPHINXOPTS = [] -SPHINXBUILD = "sphinx-build" -SPHINXAUTOBUILD = "sphinx-autobuild" +SPHINX_OPTS = [] +SPHINX_BUILD = "sphinx-build" +SPHINX_AUTOBUILD = "sphinx-autobuild" PAPER_SIZE = None -DOCDIR = "doc" -BUILDDIR = "build" +DOC_DIR = "doc" +BUILD_DIR = "build" # Used for user output; relative to project root -FULL_DOC_DIR = PROJECT_ROOT / DOCDIR -FULL_BUILD_PREFIX = f"{DOCDIR}/{BUILDDIR}" -FULL_BUILD_DIR = PROJECT_ROOT / FULL_BUILD_PREFIX +FULL_DOC_DIR = PROJECT_ROOT / DOC_DIR +# FULL_BUILD_PREFIX = f"{DOCDIR}/{BUILDDIR}" +FULL_BUILD_DIR = PROJECT_ROOT / BUILD_DIR # Linting @@ -68,12 +68,12 @@ def _resolve(p: PathLike, strict: bool = False) -> Path: PAPER_SIZE_OPTS[None] = [] PAPER_SIZE_OPTS["a4"] = ["-D", "latex_paper_size=a4"] PAPER_SIZE_OPTS["letter"] = ["-D", "latex_paper_size=letter"] -ALLSPHINXOPTS = ["-d", f"{BUILDDIR}/doctrees", *PAPER_SIZE_OPTS[PAPER_SIZE], *SPHINXOPTS, "."] +ALLSPHINXOPTS = ["-d", f"{BUILD_DIR}/doctrees", *PAPER_SIZE_OPTS[PAPER_SIZE], *SPHINX_OPTS, DOC_DIR] SPHINXAUTOBUILDOPTS = ["--watch", "../arcade", "--ignore", "./example_code/how_to_examples/thumbs"] # Important: the i18n builder cannot share the environment and doctrees with the others # This allows for internationalization / localization of doc. -I18NSPHINXOPTS = [*PAPER_SIZE_OPTS[PAPER_SIZE], *SPHINXOPTS, "."] +I18NSPHINXOPTS = [*PAPER_SIZE_OPTS[PAPER_SIZE], *SPHINX_OPTS, "."] # User-friendly check for dependencies and binaries @@ -163,7 +163,7 @@ def run(args: str | list[str], cd: PathLike | None = None) -> None: def run_doc(args: str | list[str]) -> None: - run(args, cd=FULL_DOC_DIR) + run(args, cd=PROJECT_ROOT) @app.command(rich_help_panel="Docs") @@ -181,9 +181,9 @@ def html(): """ to make standalone HTML files """ - run_doc([SPHINXBUILD, "-b", "html", *ALLSPHINXOPTS, f"{BUILDDIR}/html"]) + run_doc([SPHINX_BUILD, "-b", "html", *ALLSPHINXOPTS, f"{BUILD_DIR}/html"]) print() - print(f"Build finished. The HTML pages are in {FULL_BUILD_PREFIX}/html.") + print(f"Build finished. The HTML pages are in {FULL_BUILD_DIR}/html.") @app.command(rich_help_panel="Docs") @@ -192,7 +192,7 @@ def serve(): Build and serve standalone HTML files, with automatic rebuilds and live reload. """ run_doc( - [SPHINXAUTOBUILD, *SPHINXAUTOBUILDOPTS, "-b", "html", *ALLSPHINXOPTS, f"{BUILDDIR}/html"] + [SPHINX_AUTOBUILD, *SPHINXAUTOBUILDOPTS, "-b", "html", *ALLSPHINXOPTS, f"{BUILD_DIR}/html"] ) @@ -201,9 +201,9 @@ def dirhtml(): """ to make HTML files named index.html in directories """ - run_doc([SPHINXBUILD, "-b", "dirhtml", *ALLSPHINXOPTS, f"{BUILDDIR}/dirhtml"]) + run_doc([SPHINX_BUILD, "-b", "dirhtml", *ALLSPHINXOPTS, f"{BUILD_DIR}/dirhtml"]) print() - print(f"Build finished. The HTML pages are in {FULL_BUILD_PREFIX}/dirhtml.") + print(f"Build finished. The HTML pages are in {FULL_BUILD_DIR}/dirhtml.") @app.command(rich_help_panel="Additional Doc Formats") @@ -211,9 +211,9 @@ def singlehtml(): """ to make a single large HTML file """ - run_doc([SPHINXBUILD, "-b", "singlehtml", *ALLSPHINXOPTS, f"{BUILDDIR}/singlehtml"]) + run_doc([SPHINX_BUILD, "-b", "singlehtml", *ALLSPHINXOPTS, f"{BUILD_DIR}/singlehtml"]) print() - print(f"Build finished. The HTML page is in {FULL_BUILD_PREFIX}/singlehtml.") + print(f"Build finished. The HTML page is in {FULL_BUILD_DIR}/singlehtml.") @app.command(rich_help_panel="Additional Doc Formats") @@ -221,7 +221,7 @@ def pickle(): """ to make pickle files """ - run_doc([SPHINXBUILD, "-b", "pickle", *ALLSPHINXOPTS, f"{BUILDDIR}/pickle"]) + run_doc([SPHINX_BUILD, "-b", "pickle", *ALLSPHINXOPTS, f"{BUILD_DIR}/pickle"]) print() print("Build finished; now you can process the pickle files.") @@ -231,7 +231,7 @@ def json(): """ to make JSON files """ - run_doc([SPHINXBUILD, "-b", "json", *ALLSPHINXOPTS, f"{BUILDDIR}/json"]) + run_doc([SPHINX_BUILD, "-b", "json", *ALLSPHINXOPTS, f"{BUILD_DIR}/json"]) print() print("Build finished; now you can process the JSON files.") @@ -241,11 +241,11 @@ def htmlhelp(): """ to make HTML files and a HTML help project """ - run_doc([SPHINXBUILD, "-b", "htmlhelp", *ALLSPHINXOPTS, f"{BUILDDIR}/htmlhelp"]) + run_doc([SPHINX_BUILD, "-b", "htmlhelp", *ALLSPHINXOPTS, f"{BUILD_DIR}/htmlhelp"]) print() print( "Build finished; now you can run HTML Help Workshop with the" - + f".hhp project file in {FULL_BUILD_PREFIX}/htmlhelp." + + f".hhp project file in {FULL_BUILD_DIR}/htmlhelp." ) @@ -254,15 +254,15 @@ def qthelp(): """ to make HTML files and a qthelp project """ - run_doc([SPHINXBUILD, "-b", "qthelp", *ALLSPHINXOPTS, f"{BUILDDIR}/qthelp"]) + run_doc([SPHINX_BUILD, "-b", "qthelp", *ALLSPHINXOPTS, f"{BUILD_DIR}/qthelp"]) print() print( 'Build finished; now you can run "qcollectiongenerator" with the' - + f".qhcp project file in {FULL_BUILD_PREFIX}/qthelp, like this:" + + f".qhcp project file in {FULL_BUILD_DIR}/qthelp, like this:" ) - print(f"# qcollectiongenerator {FULL_BUILD_PREFIX}/qthelp/Arcade.qhcp") + print(f"# qcollectiongenerator {FULL_BUILD_DIR}/qthelp/Arcade.qhcp") print("To view the help file:") - print(f"# assistant -collectionFile {FULL_BUILD_PREFIX}/qthelp/Arcade.qhc") + print(f"# assistant -collectionFile {FULL_BUILD_DIR}/qthelp/Arcade.qhc") @app.command(rich_help_panel="Additional Doc Formats") @@ -270,9 +270,9 @@ def applehelp(): """ to make an Apple Help Book """ - run_doc([SPHINXBUILD, "-b", "applehelp", *ALLSPHINXOPTS, f"{BUILDDIR}/applehelp"]) + run_doc([SPHINX_BUILD, "-b", "applehelp", *ALLSPHINXOPTS, f"{BUILD_DIR}/applehelp"]) print() - print(f"Build finished. The help book is in {FULL_BUILD_PREFIX}/applehelp.") + print(f"Build finished. The help book is in {FULL_BUILD_DIR}/applehelp.") print( "N.B. You won't be able to view it unless you put it in" + "~/Library/Documentation/Help or install it in your application" @@ -286,12 +286,12 @@ def devhelp(): to make HTML files and a Devhelp project """ home = Path.home().expanduser().resolve(strict=True) - run_doc([SPHINXBUILD, "-b", "devhelp", *ALLSPHINXOPTS, f"{BUILDDIR}/devhelp"]) + run_doc([SPHINX_BUILD, "-b", "devhelp", *ALLSPHINXOPTS, f"{BUILD_DIR}/devhelp"]) print() print("Build finished.") print("To view the help file:") print(f"# mkdir -p {home}/.local/share/devhelp/Arcade") - print(f"# ln -s {FULL_BUILD_PREFIX}/devhelp {home}/.local/share/devhelp/Arcade") + print(f"# ln -s {FULL_BUILD_DIR}/devhelp {home}/.local/share/devhelp/Arcade") print("# devhelp") @@ -300,9 +300,9 @@ def epub(): """ to make an epub """ - run_doc([SPHINXBUILD, "-b", "epub", *ALLSPHINXOPTS, f"{BUILDDIR}/epub"]) + run_doc([SPHINX_BUILD, "-b", "epub", *ALLSPHINXOPTS, f"{BUILD_DIR}/epub"]) print() - print(f"Build finished. The epub file is in {FULL_BUILD_PREFIX}/epub.") + print(f"Build finished. The epub file is in {FULL_BUILD_DIR}/epub.") @app.command(rich_help_panel="Additional Doc Formats") @@ -310,9 +310,9 @@ def latex(): """ to make LaTeX files, you can set PAPER_SIZE=a4 or PAPER_SIZE=letter """ - run_doc([SPHINXBUILD, "-b", "latex", *ALLSPHINXOPTS, f"{BUILDDIR}/latex"]) + run_doc([SPHINX_BUILD, "-b", "latex", *ALLSPHINXOPTS, f"{BUILD_DIR}/latex"]) print() - print(f"Build finished; the LaTeX files are in {FULL_BUILD_PREFIX}/latex.") + print(f"Build finished; the LaTeX files are in {FULL_BUILD_DIR}/latex.") print( "Run `make' in that directory to run these through (pdf)latex" + "(use `make latexpdf' here to do that automatically)." @@ -324,10 +324,10 @@ def latexpdf(): """ to make LaTeX files and run them through pdflatex """ - run_doc([SPHINXBUILD, "-b", "latex", *ALLSPHINXOPTS, f"{BUILDDIR}/latex"]) + run_doc([SPHINX_BUILD, "-b", "latex", *ALLSPHINXOPTS, f"{BUILD_DIR}/latex"]) print("Running LaTeX files through pdflatex...") - run_doc(["make", "-C", f"{BUILDDIR}/latex", "all-pdf"]) - print(f"pdflatex finished; the PDF files are in {FULL_BUILD_PREFIX}/latex.") + run_doc(["make", "-C", f"{BUILD_DIR}/latex", "all-pdf"]) + print(f"pdflatex finished; the PDF files are in {FULL_BUILD_DIR}/latex.") @app.command(rich_help_panel="Additional Doc Formats") @@ -335,10 +335,10 @@ def latexpdfja(): """ to make LaTeX files and run them through platex/dvipdfmx """ - run_doc([SPHINXBUILD, "-b", "latex", *ALLSPHINXOPTS, f"{BUILDDIR}/latex"]) + run_doc([SPHINX_BUILD, "-b", "latex", *ALLSPHINXOPTS, f"{BUILD_DIR}/latex"]) print("Running LaTeX files through platex and dvipdfmx...") - run_doc(["make", "-C", f"{BUILDDIR}/latex", "all-pdf-ja"]) - print(f"pdflatex finished; the PDF files are in {FULL_BUILD_PREFIX}/latex.") + run_doc(["make", "-C", f"{BUILD_DIR}/latex", "all-pdf-ja"]) + print(f"pdflatex finished; the PDF files are in {FULL_BUILD_DIR}/latex.") @app.command(rich_help_panel="Additional Doc Formats") @@ -346,9 +346,9 @@ def text(): """ to make text files """ - run_doc([SPHINXBUILD, "-b", "text", *ALLSPHINXOPTS, f"{BUILDDIR}/text"]) + run_doc([SPHINX_BUILD, "-b", "text", *ALLSPHINXOPTS, f"{BUILD_DIR}/text"]) print() - print(f"Build finished. The text files are in {FULL_BUILD_PREFIX}/text.") + print(f"Build finished. The text files are in {FULL_BUILD_DIR}/text.") @app.command(rich_help_panel="Additional Doc Formats") @@ -356,9 +356,9 @@ def man(): """ to make manual pages """ - run_doc([SPHINXBUILD, "-b", "man", *ALLSPHINXOPTS, f"{BUILDDIR}/man"]) + run_doc([SPHINX_BUILD, "-b", "man", *ALLSPHINXOPTS, f"{BUILD_DIR}/man"]) print() - print(f"Build finished. The manual pages are in {FULL_BUILD_PREFIX}/man.") + print(f"Build finished. The manual pages are in {FULL_BUILD_DIR}/man.") @app.command(rich_help_panel="Additional Doc Formats") @@ -366,9 +366,9 @@ def texinfo(): """ to make Texinfo files """ - run_doc([SPHINXBUILD, "-b", "texinfo", *ALLSPHINXOPTS, f"{BUILDDIR}/texinfo"]) + run_doc([SPHINX_BUILD, "-b", "texinfo", *ALLSPHINXOPTS, f"{BUILD_DIR}/texinfo"]) print() - print(f"Build finished. The Texinfo files are in {FULL_BUILD_PREFIX}/texinfo.") + print(f"Build finished. The Texinfo files are in {FULL_BUILD_DIR}/texinfo.") print( "Run `make' in that directory to run these through makeinfo" + "(use `make info' here to do that automatically)." @@ -380,10 +380,10 @@ def info(): """ to make Texinfo files and run them through makeinfo """ - run_doc([SPHINXBUILD, "-b", "texinfo", *ALLSPHINXOPTS, f"{BUILDDIR}/texinfo"]) + run_doc([SPHINX_BUILD, "-b", "texinfo", *ALLSPHINXOPTS, f"{BUILD_DIR}/texinfo"]) print("Running Texinfo files through makeinfo...") - run_doc(["make", "-C", f"{BUILDDIR}/texinfo", "info"]) - print(f"makeinfo finished; the Info files are in {FULL_BUILD_PREFIX}/texinfo.") + run_doc(["make", "-C", f"{BUILD_DIR}/texinfo", "info"]) + print(f"makeinfo finished; the Info files are in {FULL_BUILD_DIR}/texinfo.") @app.command(rich_help_panel="Additional Doc Formats") @@ -391,9 +391,9 @@ def gettext(): """ to make PO message catalogs """ - run_doc([SPHINXBUILD, "-b", "gettext", *I18NSPHINXOPTS, f"{BUILDDIR}/locale"]) + run_doc([SPHINX_BUILD, "-b", "gettext", *I18NSPHINXOPTS, f"{BUILD_DIR}/locale"]) print() - print(f"Build finished. The message catalogs are in {FULL_BUILD_PREFIX}/locale.") + print(f"Build finished. The message catalogs are in {FULL_BUILD_DIR}/locale.") @app.command(rich_help_panel="Additional Doc Formats") @@ -401,9 +401,9 @@ def changes(): """ to make an overview of all changed/added/deprecated items """ - run_doc([SPHINXBUILD, "-b", "changes", *ALLSPHINXOPTS, f"{BUILDDIR}/changes"]) + run_doc([SPHINX_BUILD, "-b", "changes", *ALLSPHINXOPTS, f"{BUILD_DIR}/changes"]) print() - print(f"The overview file is in {FULL_BUILD_PREFIX}/changes.") + print(f"The overview file is in {FULL_BUILD_DIR}/changes.") @app.command(rich_help_panel="Code Quality") @@ -411,11 +411,11 @@ def linkcheck(): """ to check all external links for integrity """ - run_doc([SPHINXBUILD, "-b", "linkcheck", *ALLSPHINXOPTS, f"{BUILDDIR}/linkcheck"]) + run_doc([SPHINX_BUILD, "-b", "linkcheck", *ALLSPHINXOPTS, f"{BUILD_DIR}/linkcheck"]) print() print( "Link check complete; look for any errors in the above output " - + f"or in {FULL_BUILD_PREFIX}/linkcheck/output.txt." + + f"or in {FULL_BUILD_DIR}/linkcheck/output.txt." ) @@ -424,10 +424,10 @@ def doctest(): """ to run all doctests embedded in the documentation (if enabled) """ - run_doc([SPHINXBUILD, "-b", "doctest", *ALLSPHINXOPTS, f"{BUILDDIR}/doctest"]) + run_doc([SPHINX_BUILD, "-b", "doctest", *ALLSPHINXOPTS, f"{BUILD_DIR}/doctest"]) print( "Testing of doctests in the sources finished, look at the " - + f"results in {FULL_BUILD_PREFIX}/doctest/output.txt." + + f"results in {FULL_BUILD_DIR}/doctest/output.txt." ) @@ -436,25 +436,25 @@ def coverage(): """ to run coverage check of the documentation (if enabled) """ - run_doc([SPHINXBUILD, "-b", "coverage", *ALLSPHINXOPTS, f"{BUILDDIR}/coverage"]) + run_doc([SPHINX_BUILD, "-b", "coverage", *ALLSPHINXOPTS, f"{BUILD_DIR}/coverage"]) print( "Testing of coverage in the sources finished, look at the " - + f"results in {FULL_BUILD_PREFIX}/coverage/python.txt." + + f"results in {FULL_BUILD_DIR}/coverage/python.txt." ) @app.command(rich_help_panel="Additional Doc Formats") def xml(): - run_doc([SPHINXBUILD, "-b", "xml", *ALLSPHINXOPTS, f"{BUILDDIR}/xml"]) + run_doc([SPHINX_BUILD, "-b", "xml", *ALLSPHINXOPTS, f"{BUILD_DIR}/xml"]) print() - print(f"Build finished. The XML files are in {FULL_BUILD_PREFIX}/xml.") + print(f"Build finished. The XML files are in {FULL_BUILD_DIR}/xml.") @app.command(rich_help_panel="Additional Doc Formats") def pseudoxml(): - run_doc([SPHINXBUILD, "-b", "pseudoxml", *ALLSPHINXOPTS, f"{BUILDDIR}/pseudoxml"]) + run_doc([SPHINX_BUILD, "-b", "pseudoxml", *ALLSPHINXOPTS, f"{BUILD_DIR}/pseudoxml"]) print() - print(f"Build finished. The pseudo-XML files are in {FULL_BUILD_PREFIX}/pseudoxml.") + print(f"Build finished. The pseudo-XML files are in {FULL_BUILD_DIR}/pseudoxml.") @app.command(rich_help_panel="Code Quality")