Add MyST parser; use Sphinx Book Theme

Author: zyzzyxdonta

README.md

@@ -6,7 +6,7 @@ SPDX-FileContributor: David Pape
 
 # Software CaRD Policies
 
-This repository contains the `software_card_policies` Python library as well as the associated command line program
+This repository contains the `sc_validate` Python library as well as the associated command line program
 `sc-validate` and example policies.
 The software was written as part of the [Software CaRD](https://helmholtz-metadaten.de/en/inf-projects/softwarecard)
 project.

docs/conf.py

@@ -22,14 +22,24 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["copy_files"]
+extensions = [
+    "sphinx.ext.todo",
+    # custom:
+    "copy_files",
+    # third-party:
+    "myst_parser",
+]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+todo_include_todos = True
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
+html_theme = "sphinx_book_theme"
 html_static_path = ["_static"]

docs/index.rst

@@ -12,11 +12,21 @@ Welcome to the *Software CaRD Policies* documentation.
    This page is a work in progress.
    Some things will be missing or simply not work.
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Specification
+
+   specification/introduction
+
 .. toctree::
    :hidden:
    :maxdepth: 2
+   :caption: Other
 
-   specification/index
    example-policies/index
    validator/index
    library/index
+
+.. todo::
+
+   Rename "Other" section.

docs/specification/index.rst

@@ -0,0 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR), Forschungszentrum Jülich (FZJ)
+SPDX-License-Identifier: CC-BY-4.0
+SPDX-FileContributor: David Pape
+SPDX-FileContributor: Oliver Bertuch
+-->
+
+# Introduction
+
+```{todo}
+Add the content.
+```

docs/specification/introduction.md

@@ -29,7 +29,12 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-docs = ["sphinx>=8.0.0", "taskipy>=1.14.1"]
+docs = [
+  "sphinx>=8.0.0",
+  "myst-parser>=4.0.0",
+  "sphinx-book-theme>=1.1.4",
+  "taskipy>=1.14.1"
+]
 
 [project.scripts]
 sc-validate = "sc_validate.__main__:main"