diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 00000000..a8eb4b59 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,24 @@ +# Copyright (c) 2025, NVIDIA CORPORATION. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Build docs + +on: + pull_request: + types: [opened, synchronize, reopened, labeled, unlabeled] + workflow_call: + +jobs: + build-docs: + uses: NVIDIA-NeMo/FW-CI-templates/.github/workflows/_build_docs.yml@v0.57.0 diff --git a/docs/autodoc2_docstrings_parser.py b/docs/autodoc2_docstrings_parser.py new file mode 100644 index 00000000..1f8e1bdb --- /dev/null +++ b/docs/autodoc2_docstrings_parser.py @@ -0,0 +1,32 @@ +# Copyright (c) 2025, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# flake8: noqa +# pylint: skip-file +from docutils import nodes +from myst_parser.parsers.sphinx_ import MystParser +from sphinx.ext.napoleon.docstring import GoogleDocstring + + +class NapoleonParser(MystParser): + def parse(self, input_string: str, document: nodes.document) -> None: + # Get the Sphinx configuration + config = document.settings.env.config + + # Process with Google style + google_parsed = str(GoogleDocstring(input_string, config)) + + return super().parse(google_parsed, document) + + +Parser = NapoleonParser diff --git a/docs/conf.py b/docs/conf.py index 49aa55ae..95e4676e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,6 +44,14 @@ templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# Suppress warnings for cross-references and autodoc issues +suppress_warnings = [ + "myst.xref_missing", # Missing cross-references in included README + "myst.header", # Header level warnings from autodoc2 generated files + "autodoc2", # Autodoc2 warnings during API doc generation + "toc.not_included", # Autodoc2 index not included in main toctree +] + # -- Options for MyST Parser (Markdown) -------------------------------------- # MyST Parser settings myst_enable_extensions = [ @@ -92,3 +100,9 @@ }, } html_extra_path = ["project.json", "versions1.json"] + +# Github links can get rate limited from Github Actions +linkcheck_ignore = [ + ".*github\\.com.*", + ".*githubusercontent\\.com.*", +]