Merge pull request #10 from rolfsimoes/main

Improve documentation

CONTRIBUTING.md

@@ -18,6 +18,45 @@ For reporting issues and making feature suggestions please refer to the [issue t
 2. Install dependencies (not needed if only contributing documentation):
   - for the Python package: `pip install -r requirements.txt` into a Python 3.6+ environment
 
+### Building and Deploying Documentation  
+
+#### Overview of Documentation Files  
+
+The Sphinx documentation is composed of the following key files in the `sphinx/` directory:  
+- **`index.rst`**: The main entry point, containing the table of contents and an overview of the documentation structure.  
+- **Topic-specific `.rst` files**:  
+  - `api.rst`, `dataset.rst`, `metadata.rst`, `modules.rst`, `utils.rst`: These files contain detailed information about specific aspects of the project, such as APIs, datasets, and utility functions.  
+- **`conf.py`**: Configuration file for the Sphinx build system, specifying settings like extensions, themes, and project metadata.  
+- **Assets (`img/` folder)**: Includes images used in the documentation, such as `zen-logo.png`.  
+
+You can update these files to modify or expand the documentation.  
+
+#### Steps to Build and Deploy Documentation  
+
+1. **Clean and build the documentation**:  
+   Go to the project folder and run the following commands to clean and rebuild the Sphinx documentation:  
+   ```bash
+   make clean
+   make html
+   ```  
+   The generated documentation will be located in the `./sphinx/_build/html` folder.  
+
+2. **Deploy the documentation**:  
+   Update the `docs/` folder with the new documentation files:  
+   ```bash
+   rm -fr docs/*
+   cp -r sphinx/_build/html/* docs/
+   touch docs/.nojekyll
+   ```
+
+4. **Commit and push the changes**:  
+   Add the changes and commit using the `docs` type in the commit message format:  
+   ```bash
+   git add docs  
+   git commit -m "docs: update deployed documentation"  
+   git push  
+   ```  
+
 ### Development
 
 All changes to code and documentation should be made in a separate branch, created from an up-to-date local `main`. The **branch name** must refer a open issue (``i{ISSUE_ID}``):
@@ -28,7 +67,7 @@ git pull
 git checkout -b i0
 
 git add [CHANGED FILES]
-git commit -m "closes #0; [GENERAL COMMENT]"
+git commit -m "fix(scope): resolves #0; [GENERAL COMMENT]"
 
 git checkout main
 git pull
@@ -38,8 +77,6 @@ git push
 git branch -d i0
 ```
 
-When the changes are complete a merge request may be submitted from the development branch (if you have submitted a merge request with incomplete changes, please indicate that the branch is not to be merged yet in the title of the request).
-
 If you do not have the appropriate permissions to submit new branches to the **zen** repository, you may fork this repository into your own Github namespace and submit merge requests from there.
 
 ### Commit conventions

docs/_static/alabaster.css

@@ -419,7 +419,9 @@ table.footnote td {
 }
 
 dl {
-    margin: 0;
+    margin-left: 0;
+    margin-right: 0;
+    margin-top: 0;
     padding: 0;
 }
 

docs/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -222,7 +222,7 @@ table.modindextable td {
 /* -- general body styles --------------------------------------------------- */
 
 div.body {
-    min-width: 450px;
+    min-width: 360px;
     max-width: 800px;
 }
 
@@ -237,16 +237,6 @@ a.headerlink {
     visibility: hidden;
 }
 
-a.brackets:before,
-span.brackets > a:before{
-    content: "[";
-}
-
-a.brackets:after,
-span.brackets > a:after {
-    content: "]";
-}
-
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
 h3:hover > a.headerlink,
@@ -335,12 +325,16 @@ p.sidebar-title {
     font-weight: bold;
 }
 
+nav.contents,
+aside.topic,
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
 
+nav.contents,
+aside.topic,
 div.topic {
     border: 1px solid #ccc;
     padding: 7px;
@@ -379,13 +373,17 @@ div.body p.centered {
 
 div.sidebar > :last-child,
 aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
 div.topic > :last-child,
 div.admonition > :last-child {
     margin-bottom: 0;
 }
 
 div.sidebar::after,
 aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
 div.topic::after,
 div.admonition::after,
 blockquote::after {
@@ -428,10 +426,6 @@ table.docutils td, table.docutils th {
     border-bottom: 1px solid #aaa;
 }
 
-table.footnote td, table.footnote th {
-    border: 0 !important;
-}
-
 th {
     text-align: left;
     padding-right: 5px;
@@ -615,19 +609,26 @@ ul.simple p {
     margin-bottom: 0;
 }
 
-dl.footnote > dt,
-dl.citation > dt {
+aside.footnote > span,
+div.citation > span {
     float: left;
-    margin-right: 0.5em;
 }
-
-dl.footnote > dd,
-dl.citation > dd {
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+  padding-right: 0.5em;
+}
+aside.footnote > p {
+  margin-left: 2em;
+}
+div.citation > p {
+  margin-left: 4em;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
     margin-bottom: 0em;
 }
-
-dl.footnote > dd:after,
-dl.citation > dd:after {
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
     content: "";
     clear: both;
 }
@@ -644,10 +645,6 @@ dl.field-list > dt {
     padding-right: 5px;
 }
 
-dl.field-list > dt:after {
-    content: ":";
-}
-
 dl.field-list > dd {
     padding-left: 0.5em;
     margin-top: 0em;
@@ -757,6 +754,7 @@ span.pre {
     -ms-hyphens: none;
     -webkit-hyphens: none;
     hyphens: none;
+    white-space: nowrap;
 }
 
 div[class*="highlight-"] {