Develop (#30)

* Filter out directories generating pytest errors.

* Doc: fix and improve settings section.

* Homogenize versions.

* Fix sphinx-js warning.

* Move autodoc examples to doctest format.

* Exclude docs and tests from directories scanned by mypy.

* Doc: remove inherited members from Pydantic models.

* Doc: refactor config API.

* Doc: move settings API outside of config section.

Author: ebertin

docs/src/api/server/config.rst

@@ -1,6 +1,18 @@
 Config
 ======
 
+.. automodule:: visiomatic.server.config.config
+   :members:
+   :show-inheritance:
+
+.. automodule:: visiomatic.server.config.fields
+   :members:
+   :show-inheritance:
+
+.. automodule:: visiomatic.server.config.quantity
+   :members:
+   :show-inheritance:
+
 .. automodule:: visiomatic.server.config
    :members:
    :show-inheritance:

docs/src/api/server/index.rst

@@ -2,7 +2,7 @@ Python server
 =============
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    app
    cache

docs/src/api/server/settings.rst

@@ -1,7 +1,7 @@
 Settings
 ========
 
-.. automodule:: visiomatic.server.settings
+.. automodule:: visiomatic.server.config.settings
    :members:
    :show-inheritance:
 

docs/src/api/server/tiled.rst

@@ -3,7 +3,6 @@ Tiled
 
 .. automodule:: visiomatic.server.tiled
    :members:
-   :inherited-members:
    :show-inheritance:
 
 

docs/src/conf.py

@@ -20,11 +20,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'VisiOmatic'
-copyright = '2024 Emmanuel Bertin, Hervé Bouy'
+copyright = '2024 CEA/CFHT/CNRS/UParisSaclay'
 author = 'Emmanuel Bertin, Hervé Bouy'
 
 # The full version, including alpha/beta/rc tags
-release = '3.0.0'
+release = '3.0.4'
 
 
 # -- General configuration ---------------------------------------------------
@@ -42,6 +42,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.autodoc_pydantic',
     'sphinxcontrib.bibtex'
 ]
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "VisiOmatic"
-version = "3.0.3"
+version = "3.0.4"
 description = "A web application for visualizing astronomical images"
 authors = [
     {name = "Emmanuel Bertin", email = "[email protected]"},
@@ -49,6 +49,7 @@ test = [
     "pytest-cov"
 ]
 doc = [
+    "autodoc_pydantic >= 2.2.0",
     "sphinx >= 7.0",
     "sphinx-rtd-theme >= 1.2",
     "sphinxcontrib-bibtex >= 2.4.0",
@@ -76,7 +77,16 @@ mypy = "mypy src"
 pre_build = {composite = ["doc", "mypy"]}
 pre_install = {composite = ["doc", "mypy"]}
 
+[tool.mypy]
+exclude = ["docs", "tests"]
+
 [tool.pytest.ini_options]
+norecursedirs = [
+    "tests/performance",
+    "src/visiomatic/client",
+]
+addopts = "--doctest-modules --doctest-continue-on-failure"
+doctest_optionflags = "NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL ELLIPSIS"
 filterwarnings = [
     "ignore::DeprecationWarning"
 ]

src/visiomatic/client/js/control/UI.js

@@ -65,8 +65,7 @@ export const UI = Control.extend( /** @lends UI */ {
 	 * @param {boolean} [options.position='topleft']
 	   Position of the dialog on the map.
 
-	 * @see [Leaflet API reference]{@link https://leafletjs.com/reference.html#control} 
-	   for additional control options.
+	 * @see Leaflet API reference]{@link https://leafletjs.com/reference.html#control}
 
 	 * @returns {UI} VisiOmatic UI instance.
 	 */
@@ -855,10 +854,10 @@ export const UI = Control.extend( /** @lends UI */ {
  * Instantiate a VisiOmatic UI.
  * @memberof module:control/UI.js
  * @function
- * @param {VTileLayer[]} baseLayers - Array of layers
- * @param {object} [options] - Options: see {@link UI}
+ * @param {VTileLayer[]} baseLayers - Array of layers.
+ * @param {object} [options] - Options: see {@link UI}.
  * @returns {UI} VisiOmatic UI instance.
-*/
+ */
 export const ui = function (baseLayers, options) {
 	return new UI(baseLayers, options);
 };

src/visiomatic/client/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "visiomatic",
-	"version": "3.0.3",
+	"version": "3.0.4",
 	"description": "Astronomical image client viewer",
 	"homepage": "https://github.com/astromatic/visiomatic",
 	"author": "Emmanuel Bertin (CFHT/IAP/CNRS/SorbonneU/CEA/UParisSaclay)",

src/visiomatic/server/config/__init__.py

@@ -24,16 +24,13 @@ def override(key: str, value: Any) -> Any:
 
     Examples
     --------
-    ```python
-    from .config import override
+    >>> from . import override, settings
+    >>> settings['port'] = 8009
+    >>> print(f"{override('port', 8080)}")
+    8080
 
-    print(f"{override('a_setting', 10)}")
-
-    #> 10
-
-    print(f"{override('a_setting', None)}")
-
-    #> 3
+    >>> print(f"{override('port', None)}")
+    8009
 
     Parameters
     ----------
@@ -50,8 +47,6 @@ def override(key: str, value: Any) -> Any:
     return settings[key] if value is None else value
 
 
-
-if 'sphinx' not in modules:
-     config_filename = config.config_filename
-     image_filename = config.image_filename
+config_filename = config.config_filename
+image_filename = config.image_filename
 

src/visiomatic/server/config/fields.py

@@ -19,23 +19,21 @@ def SField(short: str | None = None, **kwargs) -> Any:
 
     Examples
     --------
-    ```python
-    from pydantic_settings import BaseSettings
-
-    class Settings(BaseSettings):
-        parameter: float = SField(
-            short='p',
-            description="an arbitrary parameter",
-            default=10.,
-        )
+    >>> from pydantic_settings import BaseSettings
+
+    >>> class Settings(BaseSettings):
+    ...     parameter: float = SField(
+    ...         short='p',
+    ...         description="an arbitrary parameter",
+    ...         default=10.,
+    ...     )
     
-    s = Settings(parameter=3.)
+    >>> s = Settings(parameter=3.)
     
-    print(s.model_schema_json())
-    #> {'additionalProperties': False, 'properties': {'parameter': {'default':
-    # '10.', 'description': 'an arbitrary parameter', 'short': 'p',
-    # 'title': 'Parameter', 'type': 'float'}}, 'title': 'Settings', 'type':
-    # 'object'}
+    >>> s.model_json_schema()
+    {'additionalProperties': False, 'properties': {'parameter': {'default': 10.0,
+    'description': 'an arbitrary parameter', 'short': 'p', 'title': 'Parameter',
+    'type': 'number'}}, 'title': 'Settings', 'type': 'object'}
     
     Parameters
     ----------