feat(template): Improve support for sphinx RST and MyST (#289)

osl-incubator · Jun 4, 2024 · ac6c36b · ac6c36b
1 parent b129ea9
commit ac6c36b
Show file tree

Hide file tree

Showing 20 changed files with 104 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -36,7 +36,7 @@ requirements.
 - Allows package slug (use `_` instead of `-`)
 - Licenses supported: MIT, BSD 3 Clause, ISC License, Apache Software License
   2.0, and GPL 3
-- Documentation engines: mkdocs, sphinx, jupyter-boook, quarto
+- Documentation engines: mkdocs, sphinx-rst, sphinx-myst, jupyter-boook, quarto
 - Test library: pytest, hypothesis
 - Auto format code tool: black
 - Initial integration with git

diff --git a/docs/description.md b/docs/description.md
@@ -32,8 +32,8 @@ needs.
 - **Version Control & Automation:** Includes initial git integration, conda
   (base environment) support, pre-commit hooks, continuous integration with
   GitHub Actions, and release workflows with semantic-release.
-- **Documentation:** Offers options for mkdocs, sphinx, jupyter-book or quarto
-  documentation generation.
+- **Documentation:** Offers options for mkdocs, sphinx-rst, sphinx-myst,
+  jupyter-book or quarto documentation generation.
 - **Containerization:** Provides the ability to add initial files for running
   and managing containers using Docker or Podman.
 

diff --git a/docs/guide.md b/docs/guide.md
@@ -394,9 +394,9 @@ software projects by extracting information from source code, comments and
 project metadata.
 
 Depending on your taste and the needs of your project, you should choose the
-documentation engine that best suits your needs. SciCookie offers you three
-documentation engine options for your Python package: _mkdocs_, _sphinx_,
-_jupyter-book_ and _quarto_.
+documentation engine that best suits your needs. SciCookie offers you four
+documentation engine options for your Python package: _mkdocs_, _sphinx-rst_,
+_sphinx-myst_, _jupyter-book_ and _quarto_.
 
 - [**mkdocs**](https://www.mkdocs.org/): is a fast, simple, and downright
   gorgeous static site generator for creating project documentation.
@@ -410,13 +410,15 @@ _jupyter-book_ and _quarto_.
 
 - [**Sphinx**](https://www.sphinx-doc.org/en/master/): _Sphinx_ makes it easy to
   create intelligent and attractive documentation. It provides various output
-  formats such as HTML, LaTeX, ePub, Texinfo, manual pages, plain text. It also
-  generates automatic links to functions, classes, citations, glossary terms and
-  similar information. It allows the use of built-in extensions for automatic
-  code snippet checking, the inclusion of docstrings from Python modules, and
-  third-party extensions to include many more features. _Sphinx_ uses the
-  _reStructuredText_ markup language by default and can read _MyST_ markdown
-  through third-party extensions.
+  formats such as HTML, LaTeX, ePub, Texinfo, manual pages, plain text. It
+  allows the use of built-in extensions for automatic code snippet checking, the
+  inclusion of docstrings from Python modules, and third-party extensions to
+  include many more features. To work with _Sphinx_ you can select either of the
+  two available options: _sphinx-rst_ and _sphinx-myst_. _Sphinx-rst_ uses the
+  _reStructuredText_ markup language by default and _Sphinx-myst_(Markedly
+  Structured Text - Parser) is a Sphinx and Docutils extension to parse MyST, a
+  rich and extensible flavour of Markdown for authoring technical and scientific
+  documentation.
 
 - [**Jupyter Book**](https://jupyterbook.org/en/stable/intro.html): allows you
   to create engaging, publication-quality books and documents from computational
@@ -428,11 +430,11 @@ _jupyter-book_ and _quarto_.
   HTML, PDF and static web pages. It integrates well with version control
   systems such as Git.
 
-- [Quarto](https://quarto.org/): It is a versatile open-source platform designed
-  for scientific and technical publishing. It offers the unique feature of
-  embedding Python code directly into your documentation, enabling interactive
-  and dynamic content creation. With Quarto, you can easily render your
-  documents in multiple formats such as HTML, PDF, and websites, making it
+- [**Quarto**](https://quarto.org/): It is a versatile open-source platform
+  designed for scientific and technical publishing. It offers the unique feature
+  of embedding Python code directly into your documentation, enabling
+  interactive and dynamic content creation. With Quarto, you can easily render
+  your documents in multiple formats such as HTML, PDF, and websites, making it
   convenient for sharing and presenting your work. Additionally, Quarto provides
   customization options to personalize your content according to your
   preferences and needs.

diff --git a/docs/index.md b/docs/index.md
@@ -39,7 +39,7 @@ Python package.
 - Allows package slug (use `_` instead of `-`)
 - Licenses supported: MIT, BSD 3 Clause, ISC License, Apache Software License
   2.0, and GPL 3
-- Documentation engines: mkdocs, sphinx, jupyter-boook, quarto
+- Documentation engines: mkdocs, sphinx-rst, sphinx-myst, jupyter-boook, quarto
 - Test library: pytest, hypothesis
 - Auto format code tool: black
 - Initial integration with git

diff --git a/src/scicookie/cookiecutter.json b/src/scicookie/cookiecutter.json
@@ -17,7 +17,13 @@
   ],
   "project_layout": ["src", "flat"],
   "command_line_interface": ["None", "Click", "Argparse"],
-  "documentation_engine": ["mkdocs", "sphinx", "jupyter-book", "quarto"],
+  "documentation_engine": [
+    "mkdocs",
+    "sphinx(rst)",
+    "sphinx(myst)",
+    "jupyter-book",
+    "quarto"
+  ],
   "documentation_url": "{{ cookiecutter.project_url }}",
   "code_of_conduct": [
     "None",

diff --git a/src/scicookie/hooks/post_gen_project.py b/src/scicookie/hooks/post_gen_project.py
@@ -11,19 +11,24 @@
 
 PROJECT_DIRECTORY = Path(os.path.abspath(os.path.curdir)).resolve()
 
-UNUSED_DOCS_DIRS = [
+ALL_DOCS_DIRS = [
     PROJECT_DIRECTORY / 'docs-mkdocs',
     PROJECT_DIRECTORY / 'docs-sphinx',
     PROJECT_DIRECTORY / 'docs-jupyter-book',
     PROJECT_DIRECTORY / 'docs-quarto',
 ]
 
 DOCUMENTATION_ENGINE = "{{ cookiecutter.documentation_engine }}"
-DOCS_SPEC_DIR = UNUSED_DOCS_DIRS.pop(
-    UNUSED_DOCS_DIRS.index(
-        PROJECT_DIRECTORY / f'docs-{DOCUMENTATION_ENGINE}'
-    )
-)
+{% if cookiecutter.documentation_engine == "sphinx(rst)" -%}
+DOCS_SPEC_DIR = PROJECT_DIRECTORY / 'docs-sphinx'/'rst'
+
+{% elif cookiecutter.documentation_engine == "sphinx(myst)" -%}
+DOCS_SPEC_DIR = PROJECT_DIRECTORY / 'docs-sphinx'/'myst'
+
+{% else %}
+DOCS_SPEC_DIR = PROJECT_DIRECTORY / f'docs-{DOCUMENTATION_ENGINE}'
+
+{%- endif %}
 
 USE_SRC_LAYOUT = {{ cookiecutter.project_layout == "src" }}
 if USE_SRC_LAYOUT:
@@ -112,19 +117,20 @@ def remove_package_file(filepath: str):
 def move_selected_doc_dir():
     if DOCUMENTATION_ENGINE == "mkdocs":
         docs_target_dir = PROJECT_DIRECTORY
-        remove_project_file(Path("docs/api") / "references.rst")
     else:
         docs_target_dir = PROJECT_DIRECTORY / "docs"
+
+    if DOCUMENTATION_ENGINE.startswith("sphinx"):
+        remove_project_file(Path("docs") / "index.md")
+
     for file_name in os.listdir(DOCS_SPEC_DIR):
         shutil.move(DOCS_SPEC_DIR / file_name, docs_target_dir)
 
-    if DOCUMENTATION_ENGINE == "sphinx":
-        remove_project_file(Path("docs") / "index.md")
-        remove_project_file(Path("docs/api") / "references.md")
-    if DOCUMENTATION_ENGINE == "quarto":
-        remove_project_file(Path("docs/api") / "references.md")
-        remove_project_file(Path("docs/api") / "references.rst")
-    shutil.rmtree(DOCS_SPEC_DIR)
+    if DOCUMENTATION_ENGINE.startswith("sphinx"):
+        DOCS_SPHINX = Path(DOCS_SPEC_DIR).parent
+        shutil.move(DOCS_SPHINX / 'conf.py', docs_target_dir)
+        shutil.move(DOCS_SPHINX / 'make.bat', docs_target_dir)
+        shutil.move(DOCS_SPHINX / 'readme.md', docs_target_dir)
 
 
 def clean_up_tests():
@@ -140,9 +146,9 @@ def clean_up_automation():
         remove_project_file(".makim.yaml")
 
 def clean_up_docs():
-    remove_dirs(UNUSED_DOCS_DIRS)
     move_selected_doc_dir()
-
+    remove_dirs(ALL_DOCS_DIRS)
+
 
 def clean_up_project_layout():
     if USE_SRC_LAYOUT:

diff --git a/src/scicookie/profiles/base.yaml b/src/scicookie/profiles/base.yaml
@@ -118,7 +118,8 @@ documentation_engine:
   # first choice is the default for the UI
   choices:
     - mkdocs
-    - sphinx
+    - sphinx(rst)
+    - sphinx(myst)
     - jupyter-book
     - quarto
   visible: true

diff --git a/src/scicookie/{{cookiecutter.project_slug}}/.makim.yaml b/src/scicookie/{{cookiecutter.project_slug}}/.makim.yaml
@@ -35,7 +35,7 @@ groups:
           jupyter-book build docs
           {%- elif cookiecutter.documentation_engine == "mkdocs" %}
           mkdocs build --config-file mkdocs.yaml
-          {%- elif cookiecutter.documentation_engine == "sphinx" %}
+          {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
           sphinx-apidoc -o docs/_build {{ package_path }}
           {%- elif cookiecutter.documentation_engine == "quarto" %}
           cd docs
@@ -53,8 +53,9 @@ groups:
           cd docs/_build/html/ && python -m http.server
           {%- elif cookiecutter.documentation_engine == "mkdocs" %}
           mkdocs serve --watch docs --config-file mkdocs.yaml
-          {%- elif cookiecutter.documentation_engine == "sphinx" %}
-          cd docs/_build && python -m http.server
+          {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
+          sphinx-build -M html docs/ docs/_build/
+          cd docs/_build/html && python -m http.server
           {%- elif cookiecutter.documentation_engine == "quarto" %}
           quarto preview docs
           {%- endif %}

diff --git a/src/scicookie/{{cookiecutter.project_slug}}/Makefile b/src/scicookie/{{cookiecutter.project_slug}}/Makefile
@@ -18,9 +18,9 @@ PACKAGE_PATH="{{cookiecutter.package_slug}}"
 {% endif -%}
 
 
-{%- if cookiecutter.documentation_engine == 'sphinx' %}
+{%- if cookiecutter.documentation_engine.startswith("sphinx") %}
 SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
+SPHINXBUILD   = python -m sphinx
 SPHINXPROJ    = {{ cookiecutter.project_slug }}
 SOURCEDIR     = docs/
 BUILDDIR      = docs/_build
@@ -82,7 +82,7 @@ docs-build:
 docs-preview: docs-build
 	mkdocs serve --watch docs --config-file mkdocs.yaml
 
-{%- elif cookiecutter.documentation_engine == 'sphinx' -%}
+{%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
 .PHONY:docs-build
 docs-build:
 	sphinx-apidoc -o docs/_build ${PACKAGE_PATH}

diff --git a/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-pyproject.toml b/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-pyproject.toml
@@ -70,7 +70,7 @@ dev = [
   "mkdocs-material >= 9.1.15",
   "mkdocstrings >= 0.21.2",
   "mkdocstrings-python >= 1.1.2",
-{%- elif cookiecutter.documentation_engine == 'sphinx' %}
+{%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
   "Sphinx >= 6.2.1",
   "sphinx-rtd-theme >= 1.2.2",
   "importlib-metadata >= 6.5.1",

diff --git a/src/scicookie/{{cookiecutter.project_slug}}/build-system/poetry/pyproject.toml b/src/scicookie/{{cookiecutter.project_slug}}/build-system/poetry/pyproject.toml
@@ -87,6 +87,7 @@ compose-go = ">=2.18.1"
 {% endif -%}
 ipython = "<8"
 ipykernel = ">=6.0.0"
+{# keep this line here #}
 {%- if cookiecutter.documentation_engine == 'mkdocs' %}
 Jinja2 = ">=3.1.2"
 mkdocs = ">=1.4.3"
@@ -98,7 +99,7 @@ mkdocs-material = ">=9.1.15"
 mkdocstrings = ">=0.21.2"
 mkdocstrings-python = ">=1.1.2"
 {# keep this line here #}
-{%- elif cookiecutter.documentation_engine == 'sphinx' %}
+{%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
 Sphinx = ">=6.2.1"
 sphinx-rtd-theme = ">=1.2.2"
 importlib-metadata = ">=6.5.1"

diff --git a/...ter.project_slug}}/docs/api/references.md → ...ject_slug}}/docs-mkdocs/api/references.md b/...ter.project_slug}}/docs/api/references.md → ...ject_slug}}/docs-mkdocs/api/references.md
diff --git a/src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/myst/api/references.md b/src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/myst/api/references.md
@@ -0,0 +1,15 @@
+## API references
+
+```{eval-rst}
+.. automodule:: {{cookiecutter.package_slug}}
+    :members:
+
+.. automodule:: {{cookiecutter.package_slug}}.{{cookiecutter.package_slug}}
+    :members:
+```
+
+```{admonition} API documentation with sphinx-autodoc2
+:class: important
+
+You can also build the API documentation using [sphinx-autodoc2 extension](https://sphinx-autodoc2.readthedocs.io/en/latest/). 
+```
diff --git a/src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/myst/index.md b/src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/myst/index.md
@@ -0,0 +1,20 @@
+# Welcome to OSL Python package's documentation!
+
+## Contents
+
+```{toctree}
+Introduction <readme.md>
+installation.md
+api/references.md
+Example <example.ipynb>
+contributing.md
+changelog.md
+```
+
+## Indices and tables
+
+{ref}`Index <genindex>`
+
+{ref}`Module Index <modindex>`
+
+{ref}`Search page <search>`
diff --git a/...er.project_slug}}/docs/api/references.rst → ...slug}}/docs-sphinx/rst/api/references.rst b/...er.project_slug}}/docs/api/references.rst → ...slug}}/docs-sphinx/rst/api/references.rst
diff --git a/...tter.project_slug}}/docs-sphinx/index.rst → ....project_slug}}/docs-sphinx/rst/index.rst b/...tter.project_slug}}/docs-sphinx/index.rst → ....project_slug}}/docs-sphinx/rst/index.rst
diff --git a/tests/profiles/test-depends-on.yaml b/tests/profiles/test-depends-on.yaml
@@ -122,7 +122,8 @@ documentation_engine:
   # first choice is the default for the UI
   choices:
     - mkdocs
-    - sphinx
+    - sphinx(rst)
+    - sphinx(md)
     - jupyter-book
     - quarto
   visible: true

diff --git a/tests/profiles/test-main.yaml b/tests/profiles/test-main.yaml
@@ -118,7 +118,8 @@ documentation_engine:
   # first choice is the default for the UI
   choices:
     - mkdocs
-    - sphinx
+    - sphinx(rst)
+    - sphinx(myst)
     - jupyter-book
     - quarto
   visible: true

diff --git a/tests/smoke/docs.sh b/tests/smoke/docs.sh
@@ -5,5 +5,6 @@ SMOKE_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 
 . ${SMOKE_DIR}/base.sh 'documentation_engine=mkdocs'
 . ${SMOKE_DIR}/base.sh 'documentation_engine=jupyter-book'
-. ${SMOKE_DIR}/base.sh 'documentation_engine=sphinx'
+. ${SMOKE_DIR}/base.sh 'documentation_engine=sphinx(rst)'
+. ${SMOKE_DIR}/base.sh 'documentation_engine=sphinx(myst)'
 . ${SMOKE_DIR}/base.sh 'documentation_engine=quarto'
diff --git a/tests/test_bake_project.py b/tests/test_bake_project.py
@@ -16,7 +16,7 @@ def context():
         "project_short_description": "This is an example",
         "project_url": "example.com",
         "project_version": "0.1.0",
-        "documentation_engine": "sphinx",
+        "documentation_engine": "sphinx(rst)",
     }