Addition of documenttaion pages (#16)

* Updated Sphinx documentation

New Index.rst page,
Old index.rst page became corese.rst.
Added new pages: python_api/api_root.rst with autogenerated API doc.
Added python_api/bridges.rst page
The example1.ipynb notebook is rendered as a uset_guide.
INSTALL.md is rendered as an installation page

* Added the installation of the packages from the docs/requirements.txt in case a new extension is added.

* Moved VIESION.txt to src/pycorese to update the version only in one place.

* Minor fixes and updates

Author: AnnaBobasheva

CHANGES.md

@@ -1,8 +1,19 @@
 # Changelog
 
+## Version 0.1.5
+
+- added corese-python/pycorese API documentation
+- wraps corese-core v4.6.0
+
+## Version 0.1.4
+
+- downgraded version to 0.1.4 since it's not ready for 1.0.0 yet
+- updated markdown documentation
+- wraps corese-core v4.6.0
+
 ## Version 1.0.1
 
-- document local installaiton process (INSTALL.md)
+- document local installation process (INSTALL.md)
 - build jar file then running `python -m build` (may need more work)
 - add doc skeleton and github action files
 - add coreseVersion (not fully implemented yet)

INSTALL.md

@@ -87,7 +87,7 @@ The custom `sdist` command adds the following steps:
 > [!NOTE]
 > - do not run `python setup.py` that will not build the full package.
 > - the versions of `pycorese` and Java libraries are maintained separately.
-> - `corese-python` version should be the same as `corese-core` it depends on, for simplicity reasons. 
+> - `corese-python` version should be the same as `corese-core` it depends on, for simplicity reasons.
 > -  the commands for the first two steps are provided in the [Obtaining Java libraries manually](#obtain-java-libraries-manually) section.
 
 ## Testing the package
@@ -134,7 +134,7 @@ pip install dist/pycorese-0.1.1.tar.gz
 
 ## Verifying the installation
 
-```
+```bash
 $ pip list  | grep corese
 pycorese                  0.1.1
 
@@ -148,13 +148,13 @@ $ python -c 'import pycorese'
 
 Without installing the package you can run the following command (the default Java bridge is `py4j`):
 
-```
+```bash
 ./examples/simple_query.py -j $PWD/build/libs/corese-python-4.6.0-jar-with-dependencies.jar
 ```
 
 or change the bridge to `jpype`:
 
-```
+```bash
 ./examples/simple_query.py -b jpype -j $PWD/build/libs/corese-core-4.6.0-jar-with-dependencies.jar
 ```
 

README.md

@@ -22,7 +22,7 @@
 
 **pycorese** is a Python package that provides a simple way to integrate the [corese-core](https://github.com/corese-stack/corese-core) Java library into Python applications.
 
-**pycorese** provides an intuitive API to interact with Corese's capabilities such as storage, SPARQL engine, RDFS and OWL reasoning, and SHACL validation.
+**pycorese** offers an intuitive API to interact with Corese's capabilities such as storage, SPARQL engine, RDFS and OWL reasoning, and SHACL validation.
 
 **pycorese** unlocks the potential of Semantic Web stack for applications such as semantic data analysis, knowledge graph construction, and Machine Learning.
 

VERSION.txt

@@ -22,8 +22,8 @@ sphinx-multiversion docs/source build/html
 
 ## Switcher generation
 
-- To navigate between versions by means of the switcher (the dropdown list indicating the available version), the switcher.json object must be generated. 
-- To improve navigability, a landing page must also be generated to redirect to the latest version of the documentation. 
+- To navigate between versions by means of the switcher (the dropdown list indicating the available version), the switcher.json object must be generated.
+- To improve navigability, a landing page must also be generated to redirect to the latest version of the documentation.
 
 To this end a script must be executed and write the output to the output html directory:
 
@@ -33,4 +33,4 @@ To this end a script must be executed and write the output to the output html di
 
 Both sphinx-multiversion and switcher_generator work on tags following the ```^v[0-9]+\.[0-9]+\.[0-9]+$``` syntax and ordered by refname.
 
-The minimal version set in the switcher_generator allows to not generate entries in the switcher and landing page for unexisting or uncompatible documentation.
+The minimal version set in the switcher_generator allows to not generate entries in the switcher and landing page for nonexisting or incompatible documentation.

docs/README.md

@@ -6,6 +6,7 @@ docutils<0.21,>=0.18.1
 Jinja2>=3.0
 sphinx-design==0.5.0
 myst-parser==2.0.0
+myst_nb==1.1.2
 sphinxcontrib-mermaid==0.9.2
 breathe==4.35.0
 exhale==0.3.7

docs/requirements.txt

@@ -0,0 +1,2 @@
+user_guide.ipynb
+dev_install.md

docs/source/.gitignore

@@ -1,17 +1,18 @@
-CORESE APIs
+.. The links for corese-command and corese-server are not available in the corese-stack at the moment.
+.. Using the old repository documentation at https://wimmics.github.io/corese.
+
+Corese APIs
 ###########
 
 .. toctree::
   :hidden:
 
-   Python API
-
 .. grid:: 2
 
     .. grid-item-card::
       :shadow: sm
       :class-card: sd-rounded-3
-      :link: https://corese-stack.github.io/corese-core/
+      :link: https://corese-stack.github.io/corese-core/v4.6.0/java_api/library_root.html
 
       Corese Java API
       ^^^^^^^^^^^^^^^^^^^^^^^
@@ -31,7 +32,7 @@ CORESE APIs
     .. grid-item-card::
       :shadow: sm
       :class-card: sd-rounded-3
-      :link: https://corese-stack.github.io/corese-command/
+      :link: https://wimmics.github.io/corese/cli_ref/cli_root.html
 
       Corese command-line interface
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -47,7 +48,7 @@ CORESE APIs
     .. grid-item-card::
       :shadow: sm
       :class-card: sd-rounded-3
-      :link: https://github.com/corese-stack/corese-server/
+      :link: https://wimmics.github.io/corese/rest_api/api_root.html
 
       Corese REST API
       ^^^^^^^^^^^^^^^^^^^^^^^
@@ -62,7 +63,7 @@ CORESE APIs
     .. grid-item-card::
       :shadow: sm
       :class-card: sd-rounded-3
-      :link: https://github.com/corese-stack/corese-python/
+      :link: python_api/api_root.html
 
       Corese Python API
       ^^^^^^^^^^^^^^^^^^^^^^^
@@ -73,4 +74,4 @@ CORESE APIs
       * run SPARQL queries (SELECT, CONSTRUCT, ASK, UPDATE)
       * validate RDF data against SHACL shapes
 
-            in development...
+      and more...

docs/source/apis.rst

@@ -10,71 +10,64 @@
 # add these directories to sys.path here.
 import pathlib
 import sys
-import os
+import shutil
 
-sys.path.insert(0, pathlib.Path(__file__).parents[1].resolve().as_posix())
-sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
-#sys.path.insert(0, pathlib.Path(__file__).parents[2].joinpath('code').resolve().as_posix())
+# -- Path to the Python source code ------------------------------------------------
+sys.path.insert(0, pathlib.Path(__file__).parents[2].joinpath('src').resolve().as_posix())
 
+# -- Copy files for docs --------------------------------------------------
+#
+# To avoid duplicating the information and symlinks
+shutil.copyfile(pathlib.Path(__file__).parents[2].joinpath('INSTALL.md'), "dev_install.md")
+shutil.copyfile(pathlib.Path(__file__).parents[2].joinpath('examples/example1.ipynb'), "user_guide.ipynb")
 
-project = 'CORESE-PYTHON'
+# -- Project information -----------------------------------------------------
+project = 'corese-python'
 copyright = '2024, WIMMICS'
-author = 'WIMMICS'
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = [
-    'sphinx.ext.duration', # to display the duration of Sphinx processing
-    'sphinx.ext.todo', # to include todo items in the documentation
-    # Uncomment the following lines if/when include the python code (not used in this project yet)
-    #'sphinx.ext.doctest', # to test code snippets in the documentation
-    #'sphinx.ext.autodoc', # to automatically generate documentation from docstrings
-    #'sphinx.ext.autosummary', # this extension generates function/method/attribute summary lists
-    #'sphinx.ext.autosectionlabel', # to automatically generate section labels
-    'sphinx_multiversion',
-    'sphinx_design', # to render panels
-    'myst_parser', # to parse markdown
-    'sphinxcontrib.mermaid', # to render mermaid diagrams
-    # Alternative ways to include markdown files, cannot be used together with myst_parser
-    # advantages of sphynx_mdinclude/m2r3: it can include partial markdown files
-    #
-    #'sphinx_mdinclude', # to include partial markdown files
-    #'m2r3', # to include markdown files
-    'sphinx_copybutton', # to add copy buttons to code blocks
-    ]
-
-templates_path = ['_templates']
-exclude_patterns = []
+author = 'Corese Team'
 
 # The suffix(es) of source filenames.
 source_suffix = ['.rst', '.md']
+#exclude_patterns = []
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
 
-html_theme = 'pydata_sphinx_theme'
+# Add any paths that contain data files here, relative to this directory.
 html_static_path = ['_static']
 
+# Define the css files to include in the documentation
 html_css_files = [
     "css/custom.css",
 ]
+
+# Define the js files to include in the documentation
 html_js_files = []
 
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_sidebars = {
+  #"corese": [], # syntax for hiding the sidebar
+}
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = 'python'
+
 # Project logo, to place at the top of the sidebar.
 html_logo = "_static/corese.svg"
 
 # Icon to put in the browser tab.
 html_favicon = "_static/Corese-square-logo-transparent.svg"
 
 # Modify the title to get good social-media links
-html_title = "CORESE-PYTHON"
-html_short_title = "CORESE-PYTHON"
+#html_title = "CORESE-PYTHON"
+#html_short_title = "CORESE-PYTHON"
 
 # -- Theme Options -----------------------------------------------------------
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
-# documentation.
+# documentation. https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = 'pydata_sphinx_theme'
 html_theme_options = {
      "logo": {
          "image_relative": "_static/corese.svg",
@@ -93,27 +86,78 @@
     "switcher": {"json_url": "https://corese-stack.github.io/corese-python/switcher.json", "version_match": r"v\d+\.\d+\.\d+"}
 }
 
-html_sidebars = {
-  "install": [],
-}
-
-# -- MySt-parcer extension Options -------------------------------------------
-# https://myst-parser.readthedocs.io/en/latest/
-
-myst_heading_anchors = 4
-myst_fence_as_directive = ["mermaid"]
 
-# Tell sphinx what the primary language being documented is.
-primary_domain = 'python'
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+extensions = [
+    'sphinx.ext.duration', # to display the duration of Sphinx processing
+    'sphinx.ext.todo', # to include todo items in the documentation
+    #'sphinx.ext.githubpages', # to deploy the documentation on GitHub pages ???
+    'sphinx.ext.viewcode', # to add links to the source code
+    'sphinx.ext.doctest', # to test code snippets in the documentation
+    'sphinx.ext.autodoc', # to automatically generate documentation from docstrings
+    'sphinx.ext.autosummary', # this extension generates function/method/attribute summary lists
+    'sphinx.ext.autosectionlabel', # to automatically generate section labels
+    'sphinx.ext.napoleon', # to parse Google-style docstrings
+    'sphinx_design', # to render panels
+    #'myst_parser', # to parse markdown
+    "myst_nb", # to parse jupyter notebooks and markdown files
+    #'sphinxcontrib.mermaid', # to render mermaid diagrams
+    # Alternative ways to include markdown files, cannot be used together with myst_parser
+    # advantages of sphynx_mdinclude/m2r3: it can include partial markdown files
+    #
+    #'sphinx_mdinclude', # to include partial markdown files
+    #'m2r3', # to include markdown files
+    'sphinx_copybutton', # to add copy buttons to code blocks
+    'sphinx_multiversion', # to build documentation for multiple versions
+    ]
 
-# Tell sphinx what the pygments highlight language should be.
-highlight_language = 'python'
+# -- Options for sphinx.ext.autodoc / sphinx.ext.autosummary-----------------------------
+# generate autosummary even if no references
+#autodoc_default_flags = ["members", "inherited-members"]
+autosummary_generate = True
+
+autodoc_default_options = {
+    #"member-order": "bysource",
+    #"special-members": "__init__",
+    # "undoc-members": True,
+    # "show-inheritance": True,
+    # "template": "_templates/base.rst",  # Path to your template
+}
 
-# Setup the sphinx.ext.todo extension
+# -- Options for sphinx.ext.napoleon----------------------------------------
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_rtype = False
 
-# Set to false in the final version
+# -- Setup the sphinx.ext.todo extension ------------------------------------
+# TODO: Set to false in the final version
 todo_include_todos = True
 
+# -- sphinx-multiversion extension configuration -----------------------------------
 # Optional: Exclude certain branches or tags from multi-versioning
 #smv_branch_whitelist = r'develop'  # TODO Build documentation only for feature/retrieve-doc, must be replaced with "main" for production
 smv_tag_whitelist = r'^v\d+\.\d+.*$'  # Only build tags that match version pattern like v1.0
+
+# -- MyST-NB configuration ---------------------------------------------------
+# https://myst-nb.readthedocs.io/en/latest/
+# Take the example notebook as-is, without executing it
+nb_execution_mode = "off"
+
+# Suppress warnings
+suppress_warnings = [
+    "myst.xref_missing",  # Suppress warnings about missing references after fixing the one you can fix
+    "mystnb.unknown_mime_type"  # Suppress warnings about Google Colab button in the notebook
+]
+
+# Substitute the relative path in the markdown file for the GitHub repo root URL
+def preprocess_markdown(app, docname, source):
+    base_url = "https://github.com/corese-stack/corese-python/blob/main/"
+    if docname == "dev_install":  # Replace with the actual document using the Markdown file
+        content = source[0]
+        # Replace relative paths with appropriate links
+        source[0] = content.replace("./" ,  base_url)
+
+def setup(app):
+    app.connect("source-read", preprocess_markdown)