Add documentation

docs/changes.md

@@ -0,0 +1 @@
+../CHANGES.md

docs/conf.py

@@ -0,0 +1,62 @@
+"""Configuration file for the Sphinx documentation builder."""
+import os
+
+project = "Sphinx Design Elements"
+copyright = "2023, Panodata Developers"  # noqa: A001
+author = "Panodata Developers"
+
+extensions = [
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx_design_elements",
+    "sphinx.ext.intersphinx",
+]
+
+html_theme = os.environ.get("SPHINX_THEME", "furo")
+html_title = "sphinx-design-elements"
+# html_title = f"Sphinx Design Elements ({html_theme.replace('_', '-')})"
+
+html_static_path = ["_static"]
+# html_logo = "_static/logo_wide.svg"
+# html_favicon = "_static/logo_square.svg"
+
+# if html_theme not in ("sphinx_book_theme", "pydata_sphinx_theme"):
+#    html_css_files = [
+#        "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
+#    ]
+if False and html_theme == "furo":
+    html_css_files = ["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/fontawesome.min.css"]
+    html_theme_options = {
+        "sidebar_hide_name": False,
+    }
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+myst_enable_extensions = [
+    "attrs_block",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+
+myst_substitutions = {}
+
+# Configure Sphinx-copybutton
+copybutton_remove_prompts = True
+copybutton_line_continuation_character = "\\"
+copybutton_prompt_text = r">>> |\.\.\. |\$ |sh\$ |PS> |cr> |mysql> |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
+# Configure Intersphinx
+intersphinx_mapping = {
+    "sd": ("https://sphinx-design.readthedocs.io/en/latest/", None),
+    "myst": ("https://myst-parser.readthedocs.io/en/latest/", None),
+}

docs/get_started.md

@@ -0,0 +1,77 @@
+(getting-started)=
+
+# Getting Started
+
+```{article-info}
+:author: "[Panodata Developers](https://github.com/panodata)"
+:date: "{sub-ref}`today`"
+:read-time: "1 min read"
+```
+
+
+## Setup
+
+The basic installation supports documentation authoring using the [reStructuredText]
+syntax. You can optionally support the Markdown syntax by enabling the [Markedly
+Structured Text] (MyST) syntax.
+
+### Setup with reStructuredText
+
+Install the package.
+```shell
+pip install sphinx-design-elements
+```
+
+Then, add the extension item `sphinx_design_elements` to the list of
+`extensions` within your [Sphinx] configuration file `conf.py`.
+
+```python
+extensions = [
+    "sphinx_design",
+    "sphinx_design_elements",
+]
+```
+
+
+### Setup with Markdown
+
+Install the packages.
+```shell
+pip install myst-parser sphinx-design-elements
+```
+
+Then, add the extension items `myst_parser` and `sphinx_design_elements` to the list
+of `extensions` within your [Sphinx] configuration file `conf.py`.
+When using `sphinx-design-elements` with MyST, it is also recommended to enable the
+`colon_fence` syntax extension.
+
+```python
+extensions = [
+    "myst_parser",
+    "sphinx_design",
+    "sphinx_design_elements",
+]
+myst_enable_extensions = [
+    "colon_fence",
+]
+```
+
+
+## Usage
+
+Head over to the "directives" and "roles" sections to learn about the web elements
+provided by this collection, and how to use them in your documentation markup.
+
+Both [reStructuredText] and [Markedly Structured Text] syntax are supported equally well.
+
+## Outlook
+
+Feedback and feature requests about the provided elements are always welcome.
+If you see ways to improve them, or want to add a few of your own elements you
+would like to share with others, do not hesitate to submit patches, in order to
+add them to the collection.
+
+
+[Markedly Structured Text]: https://myst-parser.readthedocs.io/
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+[Sphinx]: https://www.sphinx-doc.org/

docs/index.md

@@ -0,0 +1,103 @@
+---
+sd_hide_title: true
+---
+
+# sphinx-design
+
+::::::{div} landing-title
+:style: "padding: 0.6rem 0.1rem 0.1rem 0; background-image: linear-gradient(315deg, #992d3b 0%, #303545 84%); clip-path: polygon(0px 0px, 100% 0%, 100% calc(100% - 1.5rem), 0% 100%); -webkit-clip-path: polygon(0px 0px, 100% 0%, 100% calc(100% - 1.5rem), 0% 100%);"
+
+::::{grid}
+:reverse:
+:gutter: 2 3 3 3
+:margin: 4 4 1 2
+
+:::{grid-item}
+:columns: 12 4 4 4
+:::
+
+:::{grid-item}
+:columns: 12 8 8 8
+:child-align: justify
+:class: sd-text-white sd-fs-3
+
+A collection of composite web elements based on [![img][sphinx-design-logo]{w=200px}][sphinx-design].
+
+
+```{button-ref} get_started
+:ref-type: doc
+:outline:
+:color: white
+:class: sd-px-4 sd-fs-5
+
+Get Started
+```
+
+:::
+::::
+
+::::::
+
+Building upon sphinx-design
+: [sphinx-design] is a Sphinx extension for designing beautiful, screen-size
+  responsive web-components. It is inspired by the [Bootstrap], [Material Design],
+  and [Material-UI] design frameworks, and is the foundation for all composite
+  elements in this collection.
+
+Works with reStructuredText (rST) and Markedly Structured Text (MyST)
+: Either write documentation using the venerable [reStructuredText], or use the
+  new extended [Markdown]/[CommonMark] syntax [Markedly Structured Text]. Both
+  are supported equally well.
+
+Less markup
+: You can do everything what [sphinx-design] can do, but with less markup code,
+  so you can better focus on content instead of design and style details.
+
+Sandbox and incubator
+: [sphinx-design-elements] intends to provide a sandbox and incubation environment
+  for all details currently beyond the scope of [sphinx-design], and is very open
+  to receive further contributions in the same area.
+
+```{toctree}
+:hidden:
+
+README <readme>
+get_started
+```
+
+```{toctree}
+:caption: Development
+:hidden:
+
+project
+changes
+sandbox
+```
+
+
+::::{grid} 1 2 2 3
+:margin: 4 4 0 0
+:gutter: 1
+
+Placeholder.
+
+::::
+
+-----------
+
+Kudos to [Chris Sewell] and all contributors for conceiving and maintaining
+[MyST Parser] and [sphinx-design]. 
+
+
+[Bootstrap]: https://getbootstrap.com/
+[Chris Sewell]: https://github.com/chrisjsewell
+[CommonMark]: https://spec.commonmark.org/
+[Markdown]: https://daringfireball.net/projects/markdown/syntax
+[Markedly Structured Text]: https://myst-parser.readthedocs.io/
+[Material Design]: https://material.io
+[Material-UI]: https://material-ui.com/
+[MyST Parser]: https://myst-parser.readthedocs.io/
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+[sphinx-design]: https://sphinx-design.readthedocs.io/
+[sphinx-design-logo]: https://sphinx-design.readthedocs.io/en/latest/_static/logo_wide.svg
+[sphinx-design-elements]: https://sphinx-design-elements.readthedocs.io/

docs/project.md

@@ -0,0 +1,4 @@
+# Project information
+
+You will find all links to the documentation, the source code repository,
+and more, within the header area on the [README](#readme) document.

docs/readme.md

@@ -0,0 +1 @@
+../README.md

docs/sandbox.md

@@ -0,0 +1,14 @@
+# Sandbox
+
+Those commands will get you started with a sandboxed development environment.
+After invoking `poe check`, and observing the software tests succeed, you
+should be ready to start hacking.
+
+```shell
+git clone https://github.com/panodata/sphinx-design-elements
+cd sphinx-design-elements
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --editable=.[develop,docs,test]
+poe check
+```