From 605bec284de818a3f26c4e382f4d035c63b6f45a Mon Sep 17 00:00:00 2001 From: Alex Lowe Date: Wed, 25 Jan 2023 19:26:42 -0500 Subject: [PATCH 1/2] docs: Basic sphinx docs --- .readthedocs.yaml | 27 +++++++++++++++++ README.rst | 4 ++- docs/conf.py | 59 ++++++++++++++++++++++++++++++++++++++ docs/explanation/index.rst | 7 +++++ docs/howto/index.rst | 7 +++++ docs/index.rst | 52 +++++++++++++++++++++++++++++++++ docs/reference/index.rst | 13 +++++++++ docs/tutorials/index.rst | 11 +++++++ pyproject.toml | 9 ++++++ tox.ini | 20 +++++++++++++ 10 files changed, 208 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/conf.py create mode 100644 docs/explanation/index.rst create mode 100644 docs/howto/index.rst create mode 100644 docs/index.rst create mode 100644 docs/reference/index.rst create mode 100644 docs/tutorials/index.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..fb58117028 --- /dev/null +++ b/.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 diff --git a/README.rst b/README.rst index c0014653aa..7e7d9e4048 100644 --- a/README.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..0f1b0e4fa0 --- /dev/null +++ b/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 diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst new file mode 100644 index 0000000000..22c451229b --- /dev/null +++ b/docs/explanation/index.rst @@ -0,0 +1,7 @@ +.. _explanation: + +Explanation +********* + +.. toctree:: + :maxdepth: 1 diff --git a/docs/howto/index.rst b/docs/howto/index.rst new file mode 100644 index 0000000000..436a1880c1 --- /dev/null +++ b/docs/howto/index.rst @@ -0,0 +1,7 @@ +.. _howto: + +How-to guides +************* + +.. toctree:: + :maxdepth: 1 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..0edd1e08eb --- /dev/null +++ b/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 ` + + **Get started** with a hands-on introduction to Starcraft + + .. grid-item-card:: :ref:`How-to guides ` + + **Step-by-step guides** covering key operations and common tasks + +.. grid:: 1 1 2 2 + :reverse: + + .. grid-item-card:: :ref:`Reference ` + + **Technical information** about Starcraft + + .. grid-item-card:: :ref:`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 `_. +* `Canonical contributor licenses agreement + `_. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 0000000000..75be505951 --- /dev/null +++ b/docs/reference/index.rst @@ -0,0 +1,13 @@ +.. _reference: + +Reference +********* + +.. toctree:: + :maxdepth: 1 + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 0000000000..eeb0a5cd97 --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 49d41fdce7..30021af702 100644 --- a/pyproject.toml +++ b/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 = [ diff --git a/tox.ini b/tox.ini index eb7d09a453..59683e5b4b 100644 --- a/tox.ini +++ b/tox.ini @@ -77,3 +77,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 {posargs} docs/ +labels = lint From 77b955b5f4cf56b760734eeac3aecfbd9671f503 Mon Sep 17 00:00:00 2001 From: Alex Lowe Date: Thu, 26 Jan 2023 11:03:26 -0500 Subject: [PATCH 2/2] Configure sphinx-lint Done the same way as in rockcraft Co-authored-by: Tiago Nobrega --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 59683e5b4b..b885f1f6c6 100644 --- a/tox.ini +++ b/tox.ini @@ -95,5 +95,5 @@ 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 {posargs} docs/ +commands = sphinx-lint --ignore docs/_build --max-line-length 80 -e all {posargs} docs/ labels = lint