Merge pull request #12 from lengau/sphinx

docs: Basic sphinx docs

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+  - epub
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.rst

@@ -25,7 +25,9 @@ How to create a new project
 3. Rename any files or directories and ensure references are updated.
 4. Replace any appropriate `starcraft` references with the appropriate name.
 5. Put correct contact information into CODE_OF_CONDUCT.md
-6. Write a new README!
+6. Write a new README
+7. Import your documentation to ReadTheDocs_.
 
 .. _EditorConfig: https://editorconfig.org/
 .. _pre-commit: https://pre-commit.com/
+.. _ReadTheDocs: https://docs.readthedocs.io/en/stable/intro/import-guide.html

docs/conf.py

@@ -0,0 +1,59 @@
+# 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 = "starcraft"
+copyright = "2023, Canonical"
+author = "Canonical"
+
+# region General configuration
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx_design",
+    "sphinx_copybutton",
+    "sphinx-pydantic",
+    "sphinx_toolbox",
+    "sphinx_toolbox.more_autodoc",
+    "sphinx.ext.autodoc",  # Must be loaded after more_autodoc
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+show_authors = False
+
+# endregion
+# region Options for HTML output
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+
+# endregion
+# region Options for extensions
+# Intersphinx extension
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# Type hints configuration
+set_type_checking_flag = True
+typehints_fully_qualified = False
+always_document_param_types = True
+
+# Github config
+github_username = "canonical"
+github_repository = "starcraft-base"
+
+# endregion

docs/explanation/index.rst

@@ -0,0 +1,7 @@
+.. _explanation:
+
+Explanation
+*********
+
+.. toctree::
+   :maxdepth: 1

docs/howto/index.rst

@@ -0,0 +1,7 @@
+.. _howto:
+
+How-to guides
+*************
+
+.. toctree::
+   :maxdepth: 1

docs/index.rst

@@ -0,0 +1,52 @@
+.. starcraft documentation root file
+
+StarCraft
+=========
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   tutorials/index
+   howto/index
+   reference/index
+   explanation/index
+
+.. grid:: 1 1 2 2
+
+   .. grid-item-card:: :ref:`Tutorial <tutorial>`
+
+      **Get started** with a hands-on introduction to Starcraft
+
+   .. grid-item-card:: :ref:`How-to guides <howto>`
+
+      **Step-by-step guides** covering key operations and common tasks
+
+.. grid:: 1 1 2 2
+   :reverse:
+
+   .. grid-item-card:: :ref:`Reference <reference>`
+
+      **Technical information** about Starcraft
+
+   .. grid-item-card:: :ref:`Explanation <explanation>`
+
+      **Discussion and clarification** of key topics
+
+Project and community
+=====================
+
+Starcraft is a member of the Canonical family. It's an open source project
+that warmly welcomes community projects, contributions, suggestions, fixes
+and constructive feedback.
+
+* `Ubuntu Code of Conduct <https://ubuntu.com/community/code-of-conduct>`_.
+* `Canonical contributor licenses agreement
+  <https://ubuntu.com/legal/contributors>`_.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/reference/index.rst

@@ -0,0 +1,13 @@
+.. _reference:
+
+Reference
+*********
+
+.. toctree::
+   :maxdepth: 1
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`

docs/tutorials/index.rst

@@ -0,0 +1,11 @@
+.. _tutorial:
+
+Tutorials
+*********
+
+If you want to learn the basics from experience, then our tutorials will help
+you acquire the necessary competencies from real-life examples with fully
+reproducible steps.
+
+.. toctree::
+   :maxdepth: 1

pyproject.toml

@@ -24,6 +24,15 @@ dev = [
 ]
 types = [
 ]
+docs = [
+    "sphinx==5.3.0",
+    "sphinx-copybutton==0.5.1",
+    "sphinx-design==0.3.0",
+    "sphinx-pydantic==0.1.1",
+    "sphinx-toolbox==3.4.0",
+    "sphinx-lint==0.6.7",
+    "furo==2022.12.07",
+]
 
 [build-system]
 requires = [

tox.ini

@@ -108,3 +108,23 @@ commands =
     black: black {tty:--color} {posargs} .
     ruff: ruff --fix --respect-gitignore {posargs} .
     codespell: codespell --toml {tox_root}/pyproject.toml --write-changes {posargs}
+
+[docs]  # Sphinx documentation configuration
+extras = docs
+package = editable
+no_package = true
+env_dir = {work_dir}/docs
+runner = ignore_env_name_mismatch
+
+[testenv:sphinx-build]
+description = Build sphinx documentation
+base = docs
+allowlist_externals = bash
+commands_pre = bash -c 'if [[ ! -e docs ]];then echo "No docs directory. Run `tox run -e sphinx-quickstart` to create one.;";return 1;fi'
+commands = sphinx-build {posargs:-b html} {tox_root}/docs {tox_root}/docs/_build
+
+[testenv:lint-docs]
+description = Lint the documentation with sphinx-lint
+base = docs
+commands = sphinx-lint --ignore docs/_build --max-line-length 80 -e all {posargs} docs/
+labels = lint