Skip to content

Commit 17875df

Browse files
amotlamotl
committed
Add documentation
1 parent 623c14a commit 17875df

File tree

8 files changed

+263
-0
lines changed

8 files changed

+263
-0
lines changed

‎docs/_static/.gitkeep‎

Whitespace-only changes.

‎docs/changes.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CHANGES.md

‎docs/conf.py‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
"""Configuration file for the Sphinx documentation builder."""
2+
import os
3+
4+
project = "Sphinx Design Elements"
5+
copyright = "2023, Panodata Developers" # noqa: A001
6+
author = "Panodata Developers"
7+
8+
extensions = [
9+
"myst_parser",
10+
"sphinx_copybutton",
11+
"sphinx_design",
12+
"sphinx_design_elements",
13+
"sphinx.ext.intersphinx",
14+
]
15+
16+
html_theme = os.environ.get("SPHINX_THEME", "furo")
17+
html_title = "sphinx-design-elements"
18+
# html_title = f"Sphinx Design Elements ({html_theme.replace('_', '-')})"
19+
20+
html_static_path = ["_static"]
21+
# html_logo = "_static/logo_wide.svg"
22+
# html_favicon = "_static/logo_square.svg"
23+
24+
# if html_theme not in ("sphinx_book_theme", "pydata_sphinx_theme"):
25+
# html_css_files = [
26+
# "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
27+
# ]
28+
if False and html_theme == "furo":
29+
html_css_files = ["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/fontawesome.min.css"]
30+
html_theme_options = {
31+
"sidebar_hide_name": False,
32+
}
33+
34+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
35+
myst_enable_extensions = [
36+
"attrs_block",
37+
"attrs_inline",
38+
"colon_fence",
39+
"deflist",
40+
"fieldlist",
41+
"html_admonition",
42+
"html_image",
43+
"linkify",
44+
"replacements",
45+
"strikethrough",
46+
"substitution",
47+
"tasklist",
48+
]
49+
50+
myst_substitutions = {}
51+
52+
# Configure Sphinx-copybutton
53+
copybutton_remove_prompts = True
54+
copybutton_line_continuation_character = "\\"
55+
copybutton_prompt_text = r">>> |\.\.\. |\$ |sh\$ |PS> |cr> |mysql> |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
56+
copybutton_prompt_is_regexp = True
57+
58+
# Configure Intersphinx
59+
intersphinx_mapping = {
60+
"sd": ("https://sphinx-design.readthedocs.io/en/latest/", None),
61+
"myst": ("https://myst-parser.readthedocs.io/en/latest/", None),
62+
}

‎docs/get_started.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
(getting-started)=
2+
3+
# Getting Started
4+
5+
```{article-info}
6+
:author: "[Panodata Developers](https://github.com/panodata)"
7+
:date: "{sub-ref}`today`"
8+
:read-time: "1 min read"
9+
```
10+
11+
12+
## Setup
13+
14+
The basic installation supports documentation authoring using the [reStructuredText]
15+
syntax. You can optionally support the Markdown syntax by enabling the [Markedly
16+
Structured Text] (MyST) syntax.
17+
18+
### Setup with reStructuredText
19+
20+
Install the package.
21+
```shell
22+
pip install sphinx-design-elements
23+
```
24+
25+
Then, add the extension item `sphinx_design_elements` to the list of
26+
`extensions` within your [Sphinx] configuration file `conf.py`.
27+
28+
```python
29+
extensions = [
30+
"sphinx_design",
31+
"sphinx_design_elements",
32+
]
33+
```
34+
35+
36+
### Setup with Markdown
37+
38+
Install the packages.
39+
```shell
40+
pip install myst-parser sphinx-design-elements
41+
```
42+
43+
Then, add the extension items `myst_parser` and `sphinx_design_elements` to the list
44+
of `extensions` within your [Sphinx] configuration file `conf.py`.
45+
When using `sphinx-design-elements` with MyST, it is also recommended to enable the
46+
`colon_fence` syntax extension.
47+
48+
```python
49+
extensions = [
50+
"myst_parser",
51+
"sphinx_design",
52+
"sphinx_design_elements",
53+
]
54+
myst_enable_extensions = [
55+
"colon_fence",
56+
]
57+
```
58+
59+
60+
## Usage
61+
62+
Head over to the "directives" and "roles" sections to learn about the web elements
63+
provided by this collection, and how to use them in your documentation markup.
64+
65+
Both [reStructuredText] and [Markedly Structured Text] syntax are supported equally well.
66+
67+
## Outlook
68+
69+
Feedback and feature requests about the provided elements are always welcome.
70+
If you see ways to improve them, or want to add a few of your own elements you
71+
would like to share with others, do not hesitate to submit patches, in order to
72+
add them to the collection.
73+
74+
75+
[Markedly Structured Text]: https://myst-parser.readthedocs.io/
76+
[reStructuredText]: https://docutils.sourceforge.io/rst.html
77+
[Sphinx]: https://www.sphinx-doc.org/

‎docs/index.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
sd_hide_title: true
3+
---
4+
5+
# sphinx-design
6+
7+
::::::{div} landing-title
8+
: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%);"
9+
10+
::::{grid}
11+
:reverse:
12+
:gutter: 2 3 3 3
13+
:margin: 4 4 1 2
14+
15+
:::{grid-item}
16+
:columns: 12 4 4 4
17+
:::
18+
19+
:::{grid-item}
20+
:columns: 12 8 8 8
21+
:child-align: justify
22+
:class: sd-text-white sd-fs-3
23+
24+
A collection of composite web elements based on [![img][sphinx-design-logo]{w=200px}][sphinx-design].
25+
26+
27+
```{button-ref} get_started
28+
:ref-type: doc
29+
:outline:
30+
:color: white
31+
:class: sd-px-4 sd-fs-5
32+
33+
Get Started
34+
```
35+
36+
:::
37+
::::
38+
39+
::::::
40+
41+
Building upon sphinx-design
42+
: [sphinx-design] is a Sphinx extension for designing beautiful, screen-size
43+
responsive web-components. It is inspired by the [Bootstrap], [Material Design],
44+
and [Material-UI] design frameworks, and is the foundation for all composite
45+
elements in this collection.
46+
47+
Works with reStructuredText (rST) and Markedly Structured Text (MyST)
48+
: Either write documentation using the venerable [reStructuredText], or use the
49+
new extended [Markdown]/[CommonMark] syntax [Markedly Structured Text]. Both
50+
are supported equally well.
51+
52+
Less markup
53+
: You can do everything what [sphinx-design] can do, but with less markup code,
54+
so you can better focus on content instead of design and style details.
55+
56+
Sandbox and incubator
57+
: [sphinx-design-elements] intends to provide a sandbox and incubation environment
58+
for all details currently beyond the scope of [sphinx-design], and is very open
59+
to receive further contributions in the same area.
60+
61+
```{toctree}
62+
:hidden:
63+
64+
README <readme>
65+
get_started
66+
```
67+
68+
```{toctree}
69+
:caption: Development
70+
:hidden:
71+
72+
project
73+
changes
74+
sandbox
75+
```
76+
77+
78+
::::{grid} 1 2 2 3
79+
:margin: 4 4 0 0
80+
:gutter: 1
81+
82+
:::{grid-item-card} {octicon}`table` Placeholder
83+
:::
84+
85+
::::
86+
87+
-----------
88+
89+
Kudos to [Chris Sewell] and all contributors for conceiving and maintaining
90+
[MyST Parser] and [sphinx-design].
91+
92+
93+
[Bootstrap]: https://getbootstrap.com/
94+
[Chris Sewell]: https://github.com/chrisjsewell
95+
[CommonMark]: https://spec.commonmark.org/
96+
[Markdown]: https://daringfireball.net/projects/markdown/syntax
97+
[Markedly Structured Text]: https://myst-parser.readthedocs.io/
98+
[Material Design]: https://material.io
99+
[Material-UI]: https://material-ui.com/
100+
[MyST Parser]: https://myst-parser.readthedocs.io/
101+
[reStructuredText]: https://docutils.sourceforge.io/rst.html
102+
[sphinx-design]: https://sphinx-design.readthedocs.io/
103+
[sphinx-design-logo]: https://sphinx-design.readthedocs.io/en/latest/_static/logo_wide.svg
104+
[sphinx-design-elements]: https://sphinx-design-elements.readthedocs.io/

‎docs/project.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Project information
2+
3+
You will find all links to the documentation, the source code repository,
4+
and more, within the header area on the [README](#readme) document.

‎docs/readme.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../README.md

‎docs/sandbox.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Sandbox
2+
3+
Those commands will get you started with a sandboxed development environment.
4+
After invoking `poe check`, and observing the software tests succeed, you
5+
should be ready to start hacking.
6+
7+
```shell
8+
git clone https://github.com/panodata/sphinx-design-elements
9+
cd sphinx-design-elements
10+
python3 -m venv .venv
11+
source .venv/bin/activate
12+
pip install --editable=.[develop,docs,test]
13+
poe check
14+
```

0 commit comments

Comments
 (0)