Minor cleanup of docs (#677)

teutoburg · web-flow · commit 2678902c2477 · 2025-05-29T17:22:12.000+02:00
diff --git a/.gitignore b/.gitignore
@@ -50,7 +50,6 @@ dist
 *misc/
 *temp/
 *TEST.fits
-*temp*
 *speclecado*.fits
 *inst_pkgs/
 
diff --git a/docs/source/5_liners/loading_packages.ipynb b/docs/source/5_liners/loading_packages.ipynb
@@ -29,7 +29,7 @@
     "\n",
     "from tempfile import TemporaryDirectory\n",
     "tmpdir = TemporaryDirectory()\n",
-    "sim.rc.__config__[\"!SIM.file.local_packages_path\"] = tmpdir.name"
+    "sim.set_inst_pkgs_path(tmpdir.name)"
    ]
   },
   {
@@ -139,7 +139,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.16"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,
diff --git a/docs/source/5_liners/scopsim_templates_intro.ipynb b/docs/source/5_liners/scopsim_templates_intro.ipynb
@@ -21,7 +21,6 @@
    "source": [
     "import numpy as np\n",
     "import matplotlib.pyplot as plt\n",
-    "from matplotlib.colors import LogNorm\n",
     "\n",
     "import scopesim_templates as sim_tp"
    ]
@@ -41,9 +40,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "my_cluster = sim_tp.stellar.clusters.cluster(mass=1000.0,       # [Msun]\n",
-    "                                             distance=8000,     # [pc]\n",
-    "                                             core_radius=1)     # [pc]\n",
+    "my_cluster = sim_tp.stellar.clusters.cluster(\n",
+    "    mass=1000.0,    # [Msun]\n",
+    "    distance=8000,  # [pc]\n",
+    "    core_radius=1,  # [pc]\n",
+    ")\n",
     "my_cluster.plot()"
    ]
   },
@@ -63,18 +64,21 @@
    "outputs": [],
    "source": [
     "# See the docstring of `elliptical` for more keywords\n",
-    "my_elliptical = sim_tp.extragalactic.galaxies.elliptical(half_light_radius=30,   # [arcsec]\n",
-    "                                                         pixel_scale=0.1,        # [arcsec]\n",
-    "                                                         filter_name=\"Ks\",\n",
-    "                                                         amplitude=10,\n",
-    "                                                         normalization=\"total\",  # [Ks=10 for integrated flux]\n",
-    "                                                         n=4,                    # Sersic index    \n",
-    "                                                         ellipticity=0.5,\n",
-    "                                                         angle=30)\n",
+    "my_elliptical = sim_tp.extragalactic.galaxies.elliptical(\n",
+    "    half_light_radius=30,   # [arcsec]\n",
+    "    pixel_scale=0.1,        # [arcsec]\n",
+    "    filter_name=\"Ks\",\n",
+    "    amplitude=10,\n",
+    "    normalization=\"total\",  # [Ks=10 for integrated flux]\n",
+    "    n=4,                    # Sersic index    \n",
+    "    ellipticity=0.5,\n",
+    "    angle=30,               # [deg]\n",
+    ")\n",
     "\n",
     "plt.figure(figsize=(12, 5))\n",
     "plt.subplot(121)\n",
-    "plt.imshow(my_elliptical.fields[0].data, norm=LogNorm(), extent=[-25.6, 25.6, -25.6, 25.6])\n",
+    "plt.imshow(my_elliptical.fields[0].data, norm=\"log\",\n",
+    "           extent=[-25.6, 25.6, -25.6, 25.6])\n",
     "plt.xlabel(\"[arcsec]\")\n",
     "plt.subplot(122)\n",
     "wave = np.arange(5000, 25000)   # [angstrom]\n",
@@ -99,7 +103,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.16"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,
diff --git a/docs/source/_templates/custom-class-template.rst b/docs/source/_templates/custom-class-template.rst
@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/_templates/custom-module-template.rst b/docs/source/_templates/custom-module-template.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -57,23 +57,26 @@
 # ones.
 extensions = [
     'scopesim_sphinx_ext',
-    'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'numpydoc',
-    'matplotlib.sphinxext.plot_directive',
-    'sphinxcontrib.apidoc',
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.doctest',
+    'sphinx.ext.napoleon',
     'sphinx_copybutton',
     'myst_nb',
 ]
 
 # apidoc settings
-numpydoc_show_class_members = False
-apidoc_module_dir = pth.abspath('../../scopesim/')
-apidoc_output_dir = 'reference'
-apidoc_separate_modules = True
+autosummary_generate = True
+autoclass_content = "class"
+autodoc_default_flags = ["members", "inherited-members"]
+autodoc_docstring_signature = False
+napoleon_numpy_docstring = True
+napoleon_use_admonition_for_references = True
 apidoc_excluded_paths = ["tests/", "docs/"]
 
 # Matplotlib plot directive config parameters
diff --git a/docs/source/faqs/bind_to_local_irdb.rst b/docs/source/faqs/bind_to_local_irdb.rst
@@ -8,7 +8,7 @@ This is quite easy and involves only two steps:
 1. `Make a local copy of the IRDB`_
 2. `Tell ScopeSim where to find the IRDB`_
 
-   - `By using runtime ScopeSIm commands`_
+   - `By using runtime ScopeSim commands`_
    - `By editing the ScopeSim config file`_
 
 Make a local copy of the IRDB
@@ -32,8 +32,8 @@ By using runtime ScopeSim commands
 At the beginning of any script or jupyter notebook we can run the following command to set the default location of the instrument packages:
 This is by far the simplest method, but it requires this lone of code in every script::
 
-    import scopesim
-    scopesim.rc.__config__["!SIM.file.local_packages_path"] = "<path/to/IRDB>"
+    import scopesim as sim
+    sim.link_irdb("<path/to/IRDB>")
 
 
 By editing the ScopeSim config file
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -32,8 +32,6 @@ ScopeSim_ is on pip::
     examples/index
     5_liners/index
     faqs/index
-    effects_docstrings/index
-    Reference API <reference/modules>
 
 
 The ScopeSim python ecosystem
@@ -80,3 +78,20 @@ Contact
   - `kieran.leschinski@univie.ac.at <kieran.leschinski@univie.ac.at>`_
 
 - For friendly chat, join the slack at https://join.slack.com/t/scopesim/shared_invite/zt-143s42izo-LnyqoG7gH5j~aGn51Z~4IA
+
+API reference
+-------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+   :caption: Package Contents
+
+   scopesim.commands
+   scopesim.detector
+   scopesim.effects
+   scopesim.optics
+   scopesim.server
+   scopesim.source
+   scopesim.utils
diff --git a/scopesim/commands/user_commands.py b/scopesim/commands/user_commands.py
@@ -151,7 +151,8 @@ class UserCommands(NestedChainMap):
 
     .. versionchanged:: v0.8.0
 
-    This now inherits from (a subclass of) `collections.ChainMap`.
+       This now inherits from (a subclass of) `collections.ChainMap`.
+
     """
 
     @top_level_catch

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@`
`29`	`29`	`"\n",`
`30`	`30`	`"from tempfile import TemporaryDirectory\n",`
`31`	`31`	`"tmpdir = TemporaryDirectory()\n",`
`32`		`- "sim.rc.__config__[\"!SIM.file.local_packages_path\"] = tmpdir.name"`
	`32`	`+ "sim.set_inst_pkgs_path(tmpdir.name)"`
`33`	`33`	`]`
`34`	`34`	`},`
`35`	`35`	`{`
`@@ -139,7 +139,7 @@`
`139`	`139`	`"name": "python",`
`140`	`140`	`"nbconvert_exporter": "python",`
`141`	`141`	`"pygments_lexer": "ipython3",`
`142`		`- "version": "3.9.16"`
	`142`	`+ "version": "3.12.7"`
`143`	`143`	`}`
`144`	`144`	`},`
`145`	`145`	`"nbformat": 4,`