Skip to content

Commit 416eaa7

Browse files
authored
Merge pull request #250 from machow/docs-examples-tutorials
docs: examples and tutorials
2 parents 18c7d0a + ce8fa3f commit 416eaa7

File tree

10 files changed

+174
-55
lines changed

10 files changed

+174
-55
lines changed

docs/_quarto.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,11 @@ website:
2828
text: Get Started
2929
- file: examples/
3030
text: Examples
31+
- file: tutorials/
32+
text: Tutorials
3133
- href: api/
3234
text: Reference
35+
3336
right:
3437
- icon: github
3538
href: https://github.com/machow/quartodoc/
200 KB
Loading
206 KB
Loading
203 KB
Loading
208 KB
Loading
207 KB
Loading

docs/examples/index.qmd

Lines changed: 91 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,97 @@
1-
### Demo sites
1+
---
2+
jupyter:
3+
kernel: python3
4+
---
25

3-
| style | source | layout |
4-
| ----- | ------ | ------ |
5-
| [pkgdown] | [github][pkgdown-code] | Index page with a title and short description for functions listed in each section. Each function gets its own documentation page. |
6-
| [single-page] | [github][sp-code] | Index page has function documentation embedded on it. |
6+
:::::: {.column-page }
77

8-
### Packages using quartodoc
98

9+
```{python}
10+
#| output: asis
11+
#| echo: false
1012
11-
| package | source | about |
12-
| ----- | ------ | ------ |
13-
| [siuba] | [github][sb-code] | Data analysis library. |
14-
| [shiny][shiny] | | Dashboarding framework. |
15-
| [vetiver][vetiver] | [github][vt-code] | A tool to version, share, deploy and monitor ML models. |
13+
def gallery(entries):
14+
combined = "\n\n".join(entries)
1615
17-
: {tbl-colwidths="[20, 20, 60]"}
16+
return f":::::: {{.gallery .list .grid}}\n{combined}\n::::::"
1817
19-
[pkgdown]: /examples/pkgdown/reference
20-
[pkgdown-code]: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
21-
[single-page]: /examples/single-page/reference
22-
[sp-code]: https://github.com/machow/quartodoc/tree/main/examples/single-page
23-
[shiny]: https://shiny.rstudio.com/py/api/
24-
[vetiver]: https://rstudio.github.io/vetiver-python/stable/reference/
25-
[vt-code]: https://github.com/rstudio/vetiver-python
26-
[siuba]: https://siuba.org/api/
27-
[sb-code]: https://github.com/machow/siuba.org
18+
19+
def gallery_entry(src_thumbnail: str, href: str, title: str, href_ref=None, href_source=None):
20+
href_ref = href if href_ref is None else href_ref
21+
href_source = href if href_source is None else href_source
22+
23+
return f"""
24+
<div class="card border-2 rounded-3 g-col-12 g-col-sm-12 g-col-md-6 g-col-lg-4 mb-2">
25+
<a class="gallery-href" href="{href}">
26+
<div class="card-header py-1 px-2 border-bottom border-1 bg-light">
27+
<h6>{title}</h6>
28+
</div>
29+
<div class="gallery-card-body">
30+
<img src="{src_thumbnail}">
31+
</div>
32+
<ul class="gallery-links">
33+
<li>
34+
<a class="view-reference" href="{href_ref}">Reference Page</a>
35+
</li>
36+
<li>
37+
<a class="view-source" href="{href_source}">Source</a>
38+
</li>
39+
</ul>
40+
</a>
41+
</div>
42+
"""
43+
44+
def gallery_entry_cta():
45+
href = "https://github.com/machow/quartodoc/discussions/new?category=general&title=New%20Doc%20Site:"
46+
return f"""
47+
<div class="gallery-card-cta card border-2 rounded-3 g-col-12 g-col-sm-12 g-col-md-6 g-col-lg-4 mb-2">
48+
<a class="gallery-href" href="{href}" target="_blank">
49+
Get help creating documentation ⚡️
50+
</a>
51+
</div>
52+
"""
53+
54+
print(
55+
gallery([
56+
gallery_entry(
57+
"images/siuba-home.jpeg",
58+
"https://siuba.org",
59+
"Siuba",
60+
href_ref = "https://siuba.org/api",
61+
href_source = "https://github.com/machow/siuba.org",
62+
),
63+
gallery_entry(
64+
"images/pins-home.jpeg",
65+
"https://rstudio.github.io/pins-python",
66+
"Pins",
67+
href_ref = "https://rstudio.github.io/pins-python/reference",
68+
href_source = "http://github.com/rstudio/pins-python",
69+
),
70+
gallery_entry(
71+
"images/vetiver-home.jpeg",
72+
"https://rstudio.github.io/vetiver-python",
73+
"Vetiver",
74+
href_ref = "https://rstudio.github.io/vetiver-python/stable/reference",
75+
href_source = "https://github.com/rstudio/vetiver-python",
76+
),
77+
gallery_entry(
78+
"images/shiny-home.jpeg",
79+
"https://shiny.rstudio.com/py/",
80+
"Shiny",
81+
href_ref = "https://shiny.rstudio.com/py/api",
82+
href_source = "https://github.com/rstudio/py-shiny",
83+
),
84+
gallery_entry(
85+
"images/shinyswatch-home.jpeg",
86+
"https://rstudio.github.io/py-shinyswatch/",
87+
"Shinyswatch",
88+
href_ref = "https://rstudio.github.io/py-shinyswatch/reference",
89+
href_source = "https://github.com/rstudio/py-shinyswatch",
90+
),
91+
gallery_entry_cta()
92+
])
93+
)
94+
```
95+
96+
97+
::::::

docs/get-started/overview.qmd

Lines changed: 17 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,22 @@ jupyter:
99
name: python3
1010
---
1111

12-
::: {.callout-note}
13-
quartodoc is used to create the API documentation for [shiny], [siuba], and [vetiver].
14-
15-
It's full-featured and relatively stable, but may see some small changes in the the name of making API documentation a real delight.
16-
17-
If you're interested in using quartodoc for your package's documentation, please open an issue, so we can make sure it does exactly what you want.
18-
:::
1912

2013
quartodoc lets you quickly generate python package documentation,
2114
using markdown and [quarto](https://quarto.org).
2215
It is designed as an alternative to Sphinx.
2316

17+
Check out the screencast below for a full walkthrough of creating a documentation site,
18+
or read on for instructions on installation and use.
19+
20+
<br>
21+
22+
23+
<div style="position: relative; padding-bottom: 64.5933014354067%; height: 0;"><iframe src="https://www.loom.com/embed/fb4eb736848e470b8409ba46b514e2ed?sid=31db7652-43c6-4474-bab3-19dea2170775" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
24+
25+
<br>
26+
<br>
27+
2428
## Installation
2529

2630
```bash
@@ -125,32 +129,11 @@ quartodoc:
125129
The functions listed in `contents` are assumed to be imported from the package.
126130

127131

128-
## Example sites
129-
130-
### Demo sites
131-
132-
| style | source | layout |
133-
| ----- | ------ | ------ |
134-
| [pkgdown] | [github][pkgdown-code] | Index page with a title and short description for functions listed in each section. Each function gets its own documentation page. |
135-
| [single-page] | [github][sp-code] | Index page has function documentation embedded on it. |
136-
137-
### Packages using quartodoc
138-
139-
140-
| package | source | about |
141-
| ----- | ------ | ------ |
142-
| [siuba] | [github][sb-code] | Data analysis library. |
143-
| [shiny][shiny] | | Dashboarding framework. |
144-
| [vetiver][vetiver] | [github][vt-code] | A tool to version, share, deploy and monitor ML models. |
132+
## Learning more
145133

146-
: {tbl-colwidths="[20, 20, 60]"}
134+
Go [to the next page](./get-started/basic-docs.qmd) to learn how to configure quartodoc sites, or check out these handy pages:
147135

148-
[pkgdown]: /examples/pkgdown/reference
149-
[pkgdown-code]: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
150-
[single-page]: /examples/single-page/reference
151-
[sp-code]: https://github.com/machow/quartodoc/tree/main/examples/single-page
152-
[shiny]: https://shiny.rstudio.com/py/api/
153-
[vetiver]: https://rstudio.github.io/vetiver-python/stable/reference/
154-
[vt-code]: https://github.com/rstudio/vetiver-python
155-
[siuba]: https://siuba.org/api/
156-
[sb-code]: https://github.com/machow/siuba.org
136+
* [Examples page](./examples/index.qmd): sites using quartodoc.
137+
* [Tutorials page](./tutorials/index.qmd): screencasts of building a quartodoc site.
138+
* [Docstring issues and examples](./get-started/docstring-examples.qmd): common issues when formatting docstrings.
139+
* [Programming, the big picture](./get-started/dev-big-picture.qmd): the nitty gritty of how quartodoc works, and how to extend it.

docs/styles.css

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,54 @@ td:first-child {
6262
td:first-child a {
6363
word-break: normal;
6464
}
65+
66+
67+
/* Example Gallery */
68+
69+
.gallery .gallery-card-body {
70+
height: 250px;
71+
padding-bottom: 20px;
72+
}
73+
74+
.gallery .gallery-card-cta {
75+
font-size: 32px;
76+
text-align: center;
77+
padding: 100px 45px 45px 45px;
78+
width: 100%;
79+
background-color: rgb(248, 249, 250);
80+
}
81+
82+
.gallery a {
83+
text-decoration: none;
84+
}
85+
86+
87+
.gallery .gallery-card-body img {
88+
width: 100%;
89+
height: 100%;
90+
object-fit: contain;
91+
}
92+
93+
.gallery .card-header {
94+
font-size: 14px;
95+
text-decoration: none;
96+
text-align: center;
97+
}
98+
99+
.gallery .card-header h6 {
100+
margin-top: 0.5rem;
101+
}
102+
103+
.gallery .card-header a {
104+
text-decoration: none;
105+
}
106+
107+
.gallery-links ul {
108+
list-style-type: none;
109+
}
110+
111+
.gallery-links li {
112+
display: inline;
113+
margin-right: 60px;
114+
115+
}

docs/tutorials/index.qmd

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Tutorials
3+
---
4+
5+
6+
## Building a basic doc site
7+
8+
This screencast walks through the process of build API documentation, by re-creating
9+
the [pins API documentation](https://rstudio.github.io/pins-python/reference/) from scratch.
10+
11+
<div style="position: relative; padding-bottom: 64.5933014354067%; height: 0;"><iframe src="https://www.loom.com/embed/fb4eb736848e470b8409ba46b514e2ed?sid=31db7652-43c6-4474-bab3-19dea2170775" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
12+

0 commit comments

Comments
 (0)