Fix a lot of warnings from doxygen and sphinx

SINTEF · Oct 28, 2024 · 06342a9 · 06342a9
1 parent 56bb9a5
commit 06342a9
Show file tree

Hide file tree

Showing 31 changed files with 70 additions and 3,981 deletions.
diff --git a/bindings/python/python-protocol-plugins/file.py b/bindings/python/python-protocol-plugins/file.py
@@ -17,6 +17,7 @@ def open(self, location, options=None):
         Arguments:
             location: A URL or path to a file or directory.
             options: Supported options:
+
                 - `mode`: Combination of "r" (read), "w" (write) or "a" (append)
                   Defaults to "r" if `location` exists and "w" otherwise.
                   This default avoids accidentially overwriting an existing

diff --git a/bindings/python/python-protocol-plugins/sftp.py b/bindings/python/python-protocol-plugins/sftp.py
@@ -27,6 +27,7 @@ def open(self, location, options=None):
                 qualified as `username:password@host:port`.  In the latter
                 case the port/username/password takes precedence over `options`.
             options: Supported options:
+
                 - `username`: User name.
                 - `password`: Password.
                 - `hostname`: Host name.
@@ -47,14 +48,15 @@ def open(self, location, options=None):
                   For compresison "bzip2"; 1 to 9 are valid.
 
         Example:
-
-            # For key-based authorisation, you may get the `key_type` and
-            # `key_bytes` arguments as follows:
-            pkey = paramiko.Ed25519Key.from_private_key_file(
-                "/home/john/.ssh/id_ed25519"
-            )
-            key_type = pkey.name
-            key_bytes = pkey.asbytes().hex()
+            Here is an example of how you can use a private ssh-key
+
+                >>> # For key-based authorisation, you may get the `key_type`
+                >>> # and `key_bytes` arguments as follows:
+                >>> pkey = paramiko.Ed25519Key.from_private_key_file(
+                ...     "/home/john/.ssh/id_ed25519"
+                ... )
+                >>> key_type = pkey.name
+                >>> key_bytes = pkey.asbytes().hex()
 
         """
         options = Options(options, "port=22;compression=lzma")

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -16,9 +16,10 @@ set(SPHINX_INDEX_FILE "${SPHINX_HTML_DIR}/index.html")
 # Doxygen intput source directory
 set(DOXYGEN_INPUT_DIRS
   ${dlite_SOURCE_DIR}/src/utils
+  ${dlite_SOURCE_DIR}/src/utils/compat-src
   ${dlite_SOURCE_DIR}/src
   ${dlite_SOURCE_DIR}/src/pyembed
-  #${dlite_BINARY_DIR}/bindings/python/dlite
+  ${dlite_SOURCE_DIR}/src/tests/minunit
 )
 string(REPLACE ";" " " DOXYGEN_INPUT "${DOXYGEN_INPUT_DIRS}")
 

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -815,7 +815,8 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = @dlite_SOURCE_DIR@/src/tests \
+                         @dlite_SOURCE_DIR@/src/utils/jsmn.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -831,7 +832,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */tests/* \
+EXCLUDE_PATTERNS       = */tests/test_* \
                          */old/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
@@ -843,7 +844,10 @@ EXCLUDE_PATTERNS       = */tests/* \
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = _WDIR _wdirent __attribute__
+
+
+
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include

diff --git a/doc/_static/datamodel.png b/doc/_static/datamodel.png
diff --git a/doc/_static/storage-protocol.png b/doc/_static/storage-protocol.png
diff --git a/doc/getting_started/about.md b/doc/getting_started/about.md
@@ -18,7 +18,7 @@ By default, DLite defines four levels of metadata; instance, metadata, metadata
 The basic metadata schema describes itself, so no further meta levels are needed.
 The core idea behind these levels is if two different systems describe their data models in terms of the basic metadata schema, they can easily be made semantically interoperable, while using different metadata schemas.
 
-![The datamodel of DLite.](../../_static/datamodel.svg)
+![The datamodel of DLite.](https://raw.githubusercontent.com/SINTEF/dlite/master/doc/_static/datamodel.svg)
 
 An alternative and more flexible way to enable interoperability is to use ontologies.
 DLite provides a specialised _Instance_ called _Collection_.
@@ -46,5 +46,5 @@ See [](features.md) for a more detailed list.
 - Bindings to C, Python and Fortran.
 
 [SOFT]: https://www.sintef.no/en/publications/publication/1553408/
-[user guide]: ../../user_guide/concepts.md
-[MIT license]: ../../../license.md
+[user guide]: https://sintef.github.io/dlite/user_guide/index.html
+[MIT license]: https://sintef.github.io/dlite/license.html
diff --git a/doc/getting_started/build/build.md b/doc/getting_started/build/build.md
@@ -120,7 +120,6 @@ Using [Visual Studio Code] (VS Code) it is possible to do development on the sys
 [Python]: https://www.python.org/
 [NumPy]: https://pypi.org/project/numpy/
 [SWIG]: https://www.swig.org/
-[virtualenvwrapper]: https://pypi.org/project/virtualenvwrapper/
 [cppcheck]: http://cppcheck.sourceforge.net/
 [Doxygen]: http://www.doxygen.org/
 [Sphinx]: https://www.sphinx-doc.org/

diff --git a/doc/user_guide/protocol_plugins.md b/doc/user_guide/protocol_plugins.md
@@ -3,7 +3,7 @@ Protocol plugins
 Protocol plugins is a new feature of DLite that allow a clear separation between serialising/parsing DLite instances to/from external data representations and transferring data to/from external data resources.
 This is illustrated in the Figure below.
 
-![DLite storage and protocol plugins.](../../_static/storage-protocol.svg)
+![DLite storage and protocol plugins.](https://raw.githubusercontent.com/SINTEF/dlite/master/doc/_static/storage-protocol.svg)
 
 It allows to mix and match different protocol and storage plugins, thereby reducing the total number of plugins that has to be implemented.
 

diff --git a/src/pyembed/dlite-python-storage.h b/src/pyembed/dlite-python-storage.h
@@ -67,12 +67,4 @@ void *dlite_python_storage_load(void);
 void dlite_python_storage_unload(void);
 
 
-/**
-  Returns the base class for storage plugins.
-*/
-#ifndef NOPYTHON
-PyObject *dlite_python_storage_base(void);
-#endif
-
-
 #endif /* _DLITE_PYTHON_STORAGE_H */
diff --git a/src/utils/CMakeLists.txt b/src/utils/CMakeLists.txt
@@ -289,7 +289,7 @@ if(NOT (HAVE_SNPRINTF OR HAVE__SNPRINTF) OR
    NOT (HAVE_ASPRINTF OR HAVE__ASPRINTF) OR
    NOT (HAVE_VASPRINTF OR HAVE__VASPRINTF))
   set(WITH_SNPRINTF 1)
-  configure_file(compat/config_snprintf.h.in config_snprintf.h)
+  configure_file(compat-src/config_snprintf.h.in config_snprintf.h)
 endif()
 
 
@@ -328,14 +328,14 @@ set(sources
   uuid4.c
   )
 if(NOT HAVE_GETOPT)
-  list(APPEND sources compat/getopt.c)
+  list(APPEND sources compat-src/getopt.c)
 endif()
 if(WITH_SNPRINTF)
-  list(APPEND sources compat/snprintf.c)
+  list(APPEND sources compat-src/snprintf.c)
   add_definitions(-DHAVE_CONFIG_SNPRINTF_H)
 endif()
 if(NOT HAVE_REALPATH AND UNIX)
-  list(APPEND sources compat/realpath.c)
+  list(APPEND sources compat-src/realpath.c)
 endif()
 
 add_definitions(
@@ -416,8 +416,8 @@ install(
 
 install(
   FILES
-    compat/dirent.h
-    compat/getopt.h
+    compat-src/dirent.h
+    compat-src/getopt.h
   DESTINATION include/dlite/utils/compat
   )
 

diff --git a/src/utils/LICENSES.txt b/src/utils/LICENSES.txt
@@ -91,8 +91,8 @@ Copyright (c) 2012-16 David Ireland, DI Management Services Pty Ltd
 <http://www.di-mgt.com.au/contact/>.
 
 
-License for compat/realpath.c
------------------------------
+License for compat-src/realpath.c
+---------------------------------
 Copyright (c) 2003 Constantin S. Svintsoff <kostik@iclub.nsu.ru>
 
 Redistribution and use in source and binary forms, with or without
@@ -120,8 +120,8 @@ OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.
 
 
-Lisense for compat/snprintf.c
------------------------------
+Lisense for compat-src/snprintf.c
+---------------------------------
 Copyright (c) 1995 Patrick Powell.
 
 This code is based on code written by Patrick Powell <papowell@astart.com>.

diff --git a/src/utils/README.md b/src/utils/README.md
@@ -9,7 +9,7 @@ in the list below.
 
 Content of this library:
 
-- compat/ -- subdir with compatibility implementations for non-POSIX systems
+- compat-src/ -- subdir with compatibility implementations for non-POSIX systems
     - license: varies, MIT-compatible
     - declared in: config.h
     - depends on: config.h generated by cmake

diff --git a/src/utils/compat.h b/src/utils/compat.h
@@ -4,16 +4,16 @@
  *
  * Distributed under terms of the MIT license.
  */
+#ifndef _COMPAT_H
+#define _COMPAT_H
 
 /**
   @file
   @brief auxiliary compatibility functions
 
-  Note that the declarations for the functions found in the compat/
+  Note that the declarations for the functions found in the compat-src/
   subdirectory are provided in config.h.in.
 */
-#ifndef _COMPAT_H
-#define _COMPAT_H
 
 #include <stdlib.h>
 #ifdef WIN32
@@ -36,7 +36,7 @@
 #endif
 
 /*
- * compat/realpath.c
+ * compat-src/realpath.c
  */
 
 /** realpath() - return the canonicalized absolute pathname */
@@ -46,7 +46,7 @@ char *realpath(const char *path, char *resolved);
 
 
 /*
- * compat/snprintf.c
+ * compat-src/snprintf.c
  */
 
 /** snprintf() - write formatted output to sized buffer */

diff --git a/src/utils/compat/config_snprintf.h.in b/src/utils/compat/config_snprintf.h.in