feat(template): Add API documentation to the template 2/4 (Sphinx) (#124

)

* Add the necessary dependencies in pyproject.toml and conf.py, to generate the API documentation with sphinx.
* Remove unusable file in sphinx (post_gen_project.py)
* Create and edit the file for automatic API documentation.
* Edit the index.rst with all the files

---------

Co-authored-by: Ivan Ogasawara <ivan.ogasawara@gmail.com>

src/scicookie/hooks/post_gen_project.py

@@ -77,6 +77,7 @@ def move_selected_doc_dir():
 
     if DOCUMENTATION_ENGINE == "sphinx":
         remove_project_file(Path("docs") / "index.md")
+        remove_project_file(Path("docs/api") / "references.md")
 
     shutil.rmtree(DOCS_SPEC_DIR)
 

src/scicookie/{{cookiecutter.project_slug}}/conda/dev.yaml

@@ -7,3 +7,6 @@ dependencies:
   - poetry
   - nodejs  # used by semantic-release
   - shellcheck
+{%- if cookiecutter.documentation_engine == 'sphinx' %}
+  - pandoc
+{%- endif %}

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/conf.py

@@ -30,17 +30,20 @@
 # extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.viewcode",
-    "myst_parser"
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "nbsphinx"
 ]
 
+nbsphinx_allow_errors = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = [".rst", ".md", ".ipynb"]
+source_suffix = [".rst", ".md"]
 
 # The master toctree document.
 master_doc = "index"
@@ -69,7 +72,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".ipynb_checkpoints"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/index.rst

@@ -1,15 +1,19 @@
 Welcome to {{ cookiecutter.project_name }}'s documentation!
-======================================
+{{ "=" * ((cookiecutter.project_name|length) + 28) }}
+
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+
+   Introduction <readme>
    installation
-   modules
-   example
+   api/references
+   Example <example>
    contributing
    changelog
+
 
 Indices and tables
 ==================

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/readme.md

@@ -0,0 +1,2 @@
+```{include} ../README.md
+```

src/scicookie/{{cookiecutter.project_slug}}/docs/api/references.rst

@@ -0,0 +1,8 @@
+API references
+==============
+
+.. automodule:: {{cookiecutter.package_slug}}
+    :members:
+
+.. automodule:: {{cookiecutter.package_slug}}.{{cookiecutter.package_slug}}
+    :members:

src/scicookie/{{cookiecutter.project_slug}}/docs/example.ipynb

@@ -23,6 +23,13 @@
    "source": [
     "import {{ cookiecutter.package_slug }}"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -41,7 +48,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.10.11"
   }
  },
  "nbformat": 4,

src/scicookie/{{cookiecutter.project_slug}}/pyproject.toml

@@ -106,6 +106,8 @@ Sphinx = "^6.2.1"
 sphinx-rtd-theme = "^1.2.2"
 importlib-metadata = "^6.5.1"
 myst-parser = "^0.19.2"
+nbsphinx = "^0.9.2"
+pandoc = "^2.3"
 {% elif cookiecutter.documentation_engine == 'jupyter-book' -%}
 jupyter-book = "^0.15.1"
 myst-parser = "^0.18.1"