Add Sphinx documentation generation functionality (#2720)

* Add Sphinx documentation generation functionality

* sphinx-docs -> python/sphinx

* Use ninja instead of make

* Update copyright info in sphinx docs

* Run sphinx-apidoc before building Sphinx docs

* Cleanup Sphinx path insertion

* Don't write build outputs into source; use autoapi

* aqt -> _aqt

* Mention sphinx in development.md

---------

Co-authored-by: Damien Elmes <gpg@ankiweb.net>

build/configure/src/main.rs

@@ -28,6 +28,8 @@ use rust::check_rust;
 use web::build_and_check_web;
 use web::check_sql;
 
+use crate::python::setup_sphix;
+
 fn anki_version() -> String {
     std::fs::read_to_string(".version")
         .unwrap()
@@ -51,6 +53,8 @@ fn main() -> Result<()> {
     build_and_check_aqt(build)?;
     build_bundle(build)?;
 
+    setup_sphix(build)?;
+
     check_rust(build)?;
     check_pylib(build)?;
     check_python(build)?;

build/configure/src/python.rs

@@ -6,6 +6,7 @@ use ninja_gen::action::BuildAction;
 use ninja_gen::archives::Platform;
 use ninja_gen::build::FilesHandle;
 use ninja_gen::command::RunCommand;
+use ninja_gen::copy::CopyFiles;
 use ninja_gen::glob;
 use ninja_gen::hashmap;
 use ninja_gen::input::BuildInput;
@@ -240,3 +241,42 @@ fn add_pylint(build: &mut Build) -> Result<()> {
 
     Ok(())
 }
+
+struct Sphinx {
+    deps: BuildInput,
+}
+
+impl BuildAction for Sphinx {
+    fn command(&self) -> &str {
+        "$pip install sphinx sphinx_rtd_theme sphinx-autoapi \
+         && $python python/sphinx/build.py"
+    }
+
+    fn files(&mut self, build: &mut impl FilesHandle) {
+        build.add_inputs("python", inputs![":pyenv:bin"]);
+        build.add_inputs("pip", inputs![":pyenv:pip"]);
+        build.add_inputs("", &self.deps);
+        build.add_output_stamp("python/sphinx/stamp");
+    }
+
+    fn hide_success(&self) -> bool {
+        false
+    }
+}
+
+pub(crate) fn setup_sphix(build: &mut Build) -> Result<()> {
+    build.add_action(
+        "python:sphinx:copy_conf",
+        CopyFiles {
+            inputs: inputs![glob!("python/sphinx/{conf.py,index.rst}")],
+            output_folder: "python/sphinx",
+        },
+    )?;
+    build.add_action(
+        "python:sphinx",
+        Sphinx {
+            deps: inputs![":pylib", ":qt", ":python:sphinx:copy_conf"],
+        },
+    )?;
+    Ok(())
+}

docs/development.md

@@ -173,6 +173,20 @@ Please see [this separate page](./editing.md) for setting up an editor/IDE.
 
 See [this page](./build.md)
 
+## Generating documentation
+
+For Rust:
+
+```
+cargo doc --open
+```
+
+For Python:
+
+```
+./ninja python:sphinx && open out/python/sphinx/html/py-modindex.html
+```
+
 ## Environmental Variables
 
 If ANKIDEV is set before starting Anki, some extra log messages will be printed on stdout,

python/sphinx/build.py

@@ -0,0 +1,7 @@
+# Copyright: Ankitects Pty Ltd and contributors
+# License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html
+import os
+import subprocess
+os.environ["REPO_ROOT"] = os.path.abspath(".")
+subprocess.run(["out/pyenv/bin/sphinx-apidoc", "-o", "out/python/sphinx", "pylib", "qt"], check=True)
+subprocess.run(["out/pyenv/bin/sphinx-build", "out/python/sphinx", "out/python/sphinx/html"], check=True)

python/sphinx/conf.py

@@ -0,0 +1,19 @@
+# Copyright: Ankitects Pty Ltd and contributors
+# License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+
+project = 'Anki'
+copyright = '2023, Ankitects Pty Ltd and contributors'
+author = 'Ankitects Pty Ltd and contributors'
+
+REPO_ROOT = os.environ["REPO_ROOT"]
+
+extensions = ['sphinx_rtd_theme', 'autoapi.extension']
+html_theme = 'sphinx_rtd_theme'
+autoapi_python_use_implicit_namespaces = True
+autoapi_dirs = [os.path.join(REPO_ROOT, x) for x in ["pylib/anki", "out/pylib/anki", "qt/aqt", "out/qt/_aqt"]]

python/sphinx/index.rst

@@ -0,0 +1,20 @@
+.. Anki documentation master file, created by
+   sphinx-quickstart on Tue Sep 26 09:41:18 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Anki's documentation!
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`