accelerate building documentation

    hooks:

      - id: sphinx-build

        name: Build documentation with Sphinx

        entry: sphinx-build

        entry: make -C docs html

        language: system

        always_run: true

        exclude_types: [file, symlink]

        args:

          [

            "-M", # Run sphinx in make mode, so we can use -D flag later

                  # Note: -M requires next 3 args to be builder, source, output

            "html", # Specify builder

            "./docs", # Source directory of documents

            "./_readthedocs", # Output directory for rendered documents

            "-T", # Show full trace back on exception

            "-E", # Don't use saved env; always read all files

            "-d", # Flag for cached environment and doctrees

            "./docs/_build/doctrees", # Directory

            "-D", # Flag to override settings in conf.py

            #"exclude_patterns=notebooks/*,_build", # Exclude notebooks and build dir from pre-commit

            "exclude_patterns=_build", # Exclude notebooks and build dir from pre-commit

            "-j4", # Use multiple threads

            "-d.sphinx-cache", # Use persistent cache

          ]

        pass_filenames: false

    # Run unit tests, verify that they pass. Note that coverage is run against

    # the ./src directory here because that is what will be committed. In the

    # github workflow script, the coverage is run against the installed package

# Makefile for Sphinx documentation

#

# You can set these variables from the command line, and also

# from the environment for the first two.

SPHINXOPTS    ?= -T -E -d _build/doctrees -D language=en

EXCLUDENB     ?= -D exclude_patterns="notebooks/*","_build","**.ipynb_checkpoints"

SPHINXOPTS    ?= -j auto

SPHINXBUILD   ?= sphinx-build

SOURCEDIR     = .

BUILDDIR      = build

# Cleans up files generated by the build process

clean:

	rm -r "_build/doctrees"

	rm -r "build/doctrees"

	rm -r "$(BUILDDIR)"

# Catch-all target: route all unknown targets to Sphinx using the new

project = "lsst_inaf_agile"

copyright = "2024, Akke Viitanen"

author = "Akke Viitanen"

release = version("lsst_inaf_agile")

language = "en"

# for example take major/minor

release = version("lsst_inaf_agile")

version = ".".join(release.split(".")[:2])

release = "0.1.0"

version = "0.1"

# -- General configuration ---------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ["sphinx.ext.autodoc", "sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode"]

extensions.append("autoapi.extension")

extensions.append("nbsphinx")

copybutton_selector = "div:not(.no-copybutton) > div.highlight > pre"

templates_path = []

exclude_patterns = ["_build", "**.ipynb_checkpoints"]

exclude_patterns = ["build", "**.ipynb_checkpoints"]

# This assumes that sphinx-build is called from the root directory

master_doc = "index"

# Remove namespaces from class/method signatures

add_module_names = False

autoapi_root = "autoapi"  # Ensure this matches where your index points

autoapi_type = "python"

# autoapi_dirs = ["../src"]

autoapi_dirs = ["../src/lsst_inaf_agile"]

autoapi_ignore = ["*/__main__.py", "*/_version.py"]

conf_dir = os.path.abspath(os.path.dirname(__file__))

autoapi_dirs = [f"{conf_dir}/../src/lsst_inaf_agile"]

autoapi_ignore = [

    "*/__main__.py",

    "*/_version.py",

    "*/tests/",

    "*/data/",

]

autoapi_add_toc_tree_entry = False

autoapi_member_order = "bysource"

autoapi_keep_files = True

# autoapi_keep_files = False

html_theme = "sphinx_rtd_theme"

html_theme_options = {

napoleon_include_special_with_doc = False

nbsphinx_allow_errors = True

# Force these to be stable so extensions don't keep changing them

html_static_path = []

html_permalinks_icon = "¶"

jquery_use_sri = False

nbsphinx_requirejs_options = {}

nbsphinx_requirejs_path = ""

# Pre-executed Jupyter notebooks 

Jupyter notebooks in this directory will NOT be run in the docs workflows, and will be rendered with 

the provided output cells as-is.

This is useful for notebooks that require large datasets, access to third party APIs, large CPU or GPU requirements.

Where possible, instead write smaller notebooks that can be run as part of a github worker, and within the ReadTheDocs rendering process.

To ensure that the notebooks are not run by the notebook conversion process, you can add the following metadata block to the notebook:

```

   "nbsphinx": {

    "execute": "never"

   },

```