From a230c754b9fc0e8e42e91ee4c330aa21d8d65527 Mon Sep 17 00:00:00 2001 From: Gulshan Singh Date: Thu, 12 Oct 2023 20:03:54 -0700 Subject: [PATCH] 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 --- build/configure/src/main.rs | 4 ++++ build/configure/src/python.rs | 40 +++++++++++++++++++++++++++++++++++ docs/development.md | 14 ++++++++++++ python/sphinx/build.py | 7 ++++++ python/sphinx/conf.py | 19 +++++++++++++++++ python/sphinx/index.rst | 20 ++++++++++++++++++ 6 files changed, 104 insertions(+) create mode 100644 python/sphinx/build.py create mode 100644 python/sphinx/conf.py create mode 100644 python/sphinx/index.rst diff --git a/build/configure/src/main.rs b/build/configure/src/main.rs index 74ae90162..7c6f65133 100644 --- a/build/configure/src/main.rs +++ b/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)?; diff --git a/build/configure/src/python.rs b/build/configure/src/python.rs index 04afe996e..e7ef235fc 100644 --- a/build/configure/src/python.rs +++ b/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(()) +} diff --git a/docs/development.md b/docs/development.md index 3081cbef4..f0e986676 100644 --- a/docs/development.md +++ b/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, diff --git a/python/sphinx/build.py b/python/sphinx/build.py new file mode 100644 index 000000000..7d979c510 --- /dev/null +++ b/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) diff --git a/python/sphinx/conf.py b/python/sphinx/conf.py new file mode 100644 index 000000000..0f48c64e1 --- /dev/null +++ b/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"]] diff --git a/python/sphinx/index.rst b/python/sphinx/index.rst new file mode 100644 index 000000000..1abfd019a --- /dev/null +++ b/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`