Reducing warnings while building the docs (#1959)

.gitignore

@@ -18,6 +18,7 @@ coverage_results.*
 dist-*/
 dist/
 doc/_build
+doc/anl-afci-177
 doc/gallery
 doc/gallery-src/framework/*.yaml
 doc/tutorials/anl-afci-177*

doc/conf.py

@@ -231,17 +231,22 @@ def autodoc_skip_member_handler(app, what, name, obj, skip, options):
 def setup(app):
     """Method to make `make html` generate api documentation."""
     app.connect("autodoc-skip-member", autodoc_skip_member_handler)
-
     app.add_domain(PatchedPythonDomain, override=True)
-
     app.add_directive("exec", ExecDirective)
     app.add_directive("pyreverse", PyReverse)
+    app.add_directive("impl", directives.admonitions.Note)
+    app.add_directive("test", directives.admonitions.Note)
 
-    # copy resources needed to build the tutorial notebooks. nbsphinx_link is slick, but
-    # the working directory for running the notebooks is the directory of the link
-    # itself, so relative paths don't work.
+    # making tutorial data dir
+    dataDir = pathlib.Path("user") / ".." / "anl-afci-177"
+    if not os.path.exists(dataDir):
+        os.mkdir(dataDir)
+
+    # copy resources needed to build the tutorial notebooks. nbsphinx_link is slick, but the working
+    # directory for running the notebooks is the directory of the link itself, so relative paths
+    # don't work.
     for path in _TUTORIAL_FILES:
-        shutil.copy(path, pathlib.Path("user") / "tutorials")
+        shutil.copy(path, dataDir)
 
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -251,36 +256,36 @@ def setup(app):
 
 # -- General configuration -----------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# Add any Sphinx extension module names here, as strings. They can be extensions coming with Sphinx
+# (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "nbsphinx",
+    "nbsphinx_link",
     "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
-    "sphinx.ext.todo",
-    "sphinx.ext.mathjax",
+    "sphinx.ext.extlinks",
     "sphinx.ext.ifconfig",
+    "sphinx.ext.imgconverter",  # to convert GH Actions badge SVGs to PNG for LaTeX
     "sphinx.ext.inheritance_diagram",
-    "sphinx.ext.extlinks",
-    "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
-    "sphinxcontrib.apidoc",
-    "nbsphinx",
-    "nbsphinx_link",
-    "sphinxext.opengraph",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
     "sphinx_gallery.gen_gallery",
-    "sphinx.ext.imgconverter",  # to convert GH Actions badge SVGs to PNG for LaTeX
-    "sphinxcontrib.plantuml",
     "sphinx_rtd_theme",  # needed here for loading jquery in sphinx 6
+    "sphinxcontrib.apidoc",
     "sphinxcontrib.jquery",  # see https://github.com/readthedocs/sphinx_rtd_theme/issues/1452
+    "sphinxcontrib.plantuml",
+    "sphinxext.opengraph",
 ]
 
 # Our API should make sense without documenting private/special members.
 autodoc_default_options = {
     "members": True,
-    "undoc-members": True,
     "private-members": False,
+    "undoc-members": True,
 }
 autodoc_member_order = "bysource"
 # this line removes huge numbers of false and misleading, inherited docstrings