Merge pull request #30 from softwarepub/create-docs-page

Create basic GitHub pages for docs.

Author: zyzzyxdonta

.github/workflows/documentation.yml

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
+# SPDX-License-Identifier: CC0-1.0
+# SPDX-FileContributor: David Pape
+
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install Package
+        run: |
+          python -m pip install .[docs]
+      - name: Build Documentation
+        run: |
+          task docs-build
+      - name: Deploy to GitHub Pages Branch
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html/
+          force_orphan: true

README.md

@@ -90,6 +90,29 @@ The associated IRIs currently don't exist.
 A [search on prefix.cc](https://prefix.cc/sc) reveals prior usage of the prefix `sc:` by projects which seem to be
 defunct.
 
+## Documentation
+
+To build the documentation, install the package including the `docs` extra:
+
+```bash
+python -m pip install -e .[docs]
+```
+
+Then run Sphinx via the predefined task:
+
+```bash
+task docs-build  # build the docs
+task docs-clean  # delete the built docs
+```
+
+To view the docs in the browser, run
+
+```bash
+python -m http.server -b 127.0.0.1 -d docs/_build/html
+```
+
+Then follow the link <http://127.0.0.1:8000/>.
+
 ## Acknowledgments
 
 [Software CaRD](https://helmholtz-metadaten.de/en/inf-projects/softwarecard) (`ZT-I-PF-3-080`) is funded by the

docs/_static/.gitkeep

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileContributor: David Pape
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Software CaRD Policies"
+copyright = "2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)"
+author = "David Pape"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

docs/_templates/.gitkeep

@@ -0,0 +1,10 @@
+.. SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
+   SPDX-License-Identifier: CC-BY-4.0
+   SPDX-FileContributor: David Pape
+
+Example Policies
+================
+
+.. note::
+
+   This is a placeholder for an overview of example policies following the Software CaRD policy specification.

docs/conf.py

@@ -0,0 +1,22 @@
+.. SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
+   SPDX-License-Identifier: CC-BY-4.0
+   SPDX-FileContributor: David Pape
+
+Software CaRD Policies
+======================
+
+Welcome to the *Software CaRD Policies* documentation.
+
+.. note::
+
+   This page is a work in progress.
+   Some things will be missing or simply not work.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   specification/index
+   example-policies/index
+   validator/index
+   library/index

docs/example-policies/index.rst

@@ -0,0 +1,10 @@
+.. SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
+   SPDX-License-Identifier: CC-BY-4.0
+   SPDX-FileContributor: David Pape
+
+Library
+=======
+
+.. note::
+
+   This is a placeholder for the documentation of the ``sc_validate`` library.

docs/index.rst

@@ -0,0 +1,10 @@
+.. SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
+   SPDX-License-Identifier: CC-BY-4.0
+   SPDX-FileContributor: David Pape
+
+Specification
+=============
+
+.. note::
+
+   This is a placeholder for the Software CaRD policy specification.

docs/library/index.rst

@@ -0,0 +1,12 @@
+.. SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden - Rossendorf (HZDR)
+   SPDX-License-Identifier: CC-BY-4.0
+   SPDX-FileContributor: David Pape
+
+Validator
+=========
+
+.. note::
+
+   This is a placeholder for the documentation of the ``sc-validate`` command line tool.
+
+The validator can be run using the ``sc-validate`` command which is equivalent to ``python -m sc_validate``.