Hide private methods in API documentation (#607)

* Contrain docs dependencies
* conf.py cleanup

.readthedocs.yml

@@ -16,4 +16,4 @@ build:
         - asdf global uv 0.1.44
         - uv venv
         - uv pip install .[docs]
-        - . .venv/bin/activate && .venv/bin/python -m sphinx -W --keep-going -d _build/doctrees -D language=en -b html docs/source $READTHEDOCS_OUTPUT/html
+        - .venv/bin/python -m sphinx -W --keep-going -d _build/doctrees -D language=en -b html docs/source $READTHEDOCS_OUTPUT/html

docs/source/conf.py

@@ -1,14 +1,14 @@
-# pylint: disable=invalid-name
-
-# -*- coding: utf-8 -*-
 """Sphinx configuration for aiidalab-widgets-base."""
-import os
-import subprocess
-import sys
+
 import time
+import warnings
 from pathlib import Path
 
-from aiidalab_widgets_base import __version__  # pylint: disable=wrong-import-position
+warnings.filterwarnings(
+    "ignore", category=UserWarning, message="Creating AiiDA configuration folder .*"
+)
+
+from aiidalab_widgets_base import __version__
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -97,7 +97,7 @@
 def symlink_example_notebooks(source_dir: Path):
     """Symlink example Jupyter notebooks.
 
-    Symlinks example jupyter notebooks so that they can be
+    Symlinks example Jupyter notebooks so that they can be
     included into the documentation.
     """
     notebooks_dir = source_dir.parent.parent / "notebooks"
@@ -112,37 +112,23 @@ def run_apidoc(_):
     build on readthedocs.
     See also https://github.com/rtfd/readthedocs.org/issues/1139
     """
+    # https://github.com/readthedocs/readthedocs.org/issues/1139#issuecomment-715284488
+    from sphinx.ext.apidoc import main
+
     source_dir = Path(__file__).resolve().parent
     apidoc_dir = source_dir / "apidoc"
     package_dir = source_dir.parent.parent / "aiidalab_widgets_base"
 
     symlink_example_notebooks(source_dir)
 
-    # In #1139, they suggest the route below, but this ended up
-    # calling sphinx-build, not sphinx-apidoc
-    # from sphinx.apidoc import main
-    # main([None, '-e', '-o', apidoc_dir, package_dir, '--force'])
-
-    cmd_path = "sphinx-apidoc"
-    if hasattr(sys, "real_prefix"):  # Check to see if we are in a virtualenv
-        # If we are, assemble the path manually
-        cmd_path = os.path.abspath(os.path.join(sys.prefix, "bin", "sphinx-apidoc"))
-
     options = [
-        "-o",
-        apidoc_dir,
-        package_dir,
-        "--private",
         "--force",
         "--no-toc",
+        "-o",
+        str(apidoc_dir),
+        str(package_dir),
     ]
-
-    # See https://stackoverflow.com/a/30144019
-    env = os.environ.copy()
-    env[
-        "SPHINX_APIDOC_OPTIONS"
-    ] = "members,special-members,private-members,undoc-members,show-inheritance"
-    subprocess.check_call([cmd_path, *options], env=env)
+    main(options)
 
 
 def setup(app):

setup.cfg

@@ -62,10 +62,10 @@ smiles =
     rdkit>=2021.09.2
     scikit-learn~=1.0.0
 docs =
-    sphinx
-    sphinx-design
-    pydata-sphinx-theme
-    myst-nb
+    sphinx~=7.3
+    sphinx-design~=0.5
+    pydata-sphinx-theme~=0.15
+    myst-nb~=1.1
 
 [bumpver]
 current_version = "v2.2.2"