From 10985b2fbe3ae17ceff87bd4ffcffbc4340e6eea Mon Sep 17 00:00:00 2001 From: Brad Keryan Date: Wed, 4 Oct 2023 12:35:56 -0500 Subject: [PATCH 1/4] docs: Enable the githubpages and intersphinx extensions - githubpages: Automatically create .nojekyll file - intersphinx: Allow linking to docs for the Python stdlib and other packages --- _docs_source/conf.py | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/_docs_source/conf.py b/_docs_source/conf.py index ccf211021..67c3b7c13 100644 --- a/_docs_source/conf.py +++ b/_docs_source/conf.py @@ -9,12 +9,14 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "sphinx.ext.autodoc", "autoapi.extension", - "sphinx.ext.viewcode", - "sphinx.ext.napoleon", - "sphinx_click", "m2r2", + "sphinx_click", + "sphinx.ext.autodoc", + "sphinx.ext.githubpages", + "sphinx.ext.intersphinx", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", ] root_path = pathlib.Path(__file__).parent.parent @@ -76,6 +78,18 @@ def setup(sphinx): exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +intersphinx_mapping = { + "nidaqmx": ("https://nidaqmx-python.readthedocs.io/en/stable/", None), + "nidcpower": ("https://nidcpower.readthedocs.io/en/stable/", None), + "nidigital": ("https://nidigital.readthedocs.io/en/stable/", None), + "nidmm": ("https://nidmm.readthedocs.io/en/stable/", None), + "nifgen": ("https://nifgen.readthedocs.io/en/stable/", None), + "niniscope": ("https://niscope.readthedocs.io/en/stable/", None), + "niniswitch": ("https://niswitch.readthedocs.io/en/stable/", None), + "python": ("https://docs.python.org/3", None), +} + + # -- Options for HTML output ---------------------------------------------- From 931751326184b965cd300b8545a5e927adf2ce69 Mon Sep 17 00:00:00 2001 From: Brad Keryan Date: Wed, 4 Oct 2023 12:36:57 -0500 Subject: [PATCH 2/4] GitHub workflows: Remove `touch docs/.nojekyll` --- .github/workflows/Publish_NIMS.yml | 3 +-- .github/workflows/check_nims.yml | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/workflows/Publish_NIMS.yml b/.github/workflows/Publish_NIMS.yml index 1a381cf45..01b67e7c6 100644 --- a/.github/workflows/Publish_NIMS.yml +++ b/.github/workflows/Publish_NIMS.yml @@ -62,8 +62,7 @@ jobs: - name: Update API Reference Documents(Generated using Sphinx) run: | rm -rf docs - mkdir -p docs - touch docs/.nojekyll + mkdir -p docs poetry run sphinx-build _docs_source docs -b html - name: Commit file changes. diff --git a/.github/workflows/check_nims.yml b/.github/workflows/check_nims.yml index 309fa7dd1..87b0340ba 100644 --- a/.github/workflows/check_nims.yml +++ b/.github/workflows/check_nims.yml @@ -47,8 +47,7 @@ jobs: - name: Build docs and check for errors/warnings run: | rm -rf docs - mkdir -p docs - touch docs/.nojekyll + mkdir -p docs poetry run sphinx-build _docs_source docs -b html -W --keep-going - name: Revert docs run: git clean -dfx docs/ && git restore docs/ \ No newline at end of file From 23bbaf9faf9973a3ee78e8cc45e916f0ded61a5a Mon Sep 17 00:00:00 2001 From: Brad Keryan Date: Wed, 4 Oct 2023 13:05:21 -0500 Subject: [PATCH 3/4] docs: Fix typo in config file --- _docs_source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs_source/conf.py b/_docs_source/conf.py index 67c3b7c13..bc47ac998 100644 --- a/_docs_source/conf.py +++ b/_docs_source/conf.py @@ -84,8 +84,8 @@ def setup(sphinx): "nidigital": ("https://nidigital.readthedocs.io/en/stable/", None), "nidmm": ("https://nidmm.readthedocs.io/en/stable/", None), "nifgen": ("https://nifgen.readthedocs.io/en/stable/", None), - "niniscope": ("https://niscope.readthedocs.io/en/stable/", None), - "niniswitch": ("https://niswitch.readthedocs.io/en/stable/", None), + "niscope": ("https://niscope.readthedocs.io/en/stable/", None), + "niswitch": ("https://niswitch.readthedocs.io/en/stable/", None), "python": ("https://docs.python.org/3", None), } From 5417a68a8e2db95c037a390e27bf95ca6c8505b9 Mon Sep 17 00:00:00 2001 From: Brad Keryan Date: Wed, 4 Oct 2023 13:19:45 -0500 Subject: [PATCH 4/4] docs: Show type hints in attribute/parameter descriptions --- _docs_source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs_source/conf.py b/_docs_source/conf.py index bc47ac998..d71bf1e57 100644 --- a/_docs_source/conf.py +++ b/_docs_source/conf.py @@ -47,7 +47,7 @@ autoapi_options.remove("private-members") # note: remove this to include "_" members in docs autoapi_dirs = [root_path / "ni_measurementlink_service"] autoapi_type = "python" -autodoc_typehints = "none" +autodoc_typehints = "description" # WARNING: more than one target found for cross-reference 'MeasurementInfo':