Skip to content

Commit a392b15

Browse files
machowmachow
committed
DRAFT: examples and tutorials
1 parent 772feed commit a392b15

File tree

5 files changed

+157
-11
lines changed

5 files changed

+157
-11
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/

‎docs/examples/index.qmd‎

Lines changed: 98 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,33 @@
1-
### Demo sites
1+
---
2+
jupyter:
3+
kernel: python3
4+
---
5+
6+
:::::: {.column-page }
7+
8+
::::: {.d-none}
9+
210

311
| style | source | layout |
412
| ----- | ------ | ------ |
513
| [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. |
614
| [single-page] | [github][sp-code] | Index page has function documentation embedded on it. |
715

8-
### Packages using quartodoc
9-
1016

1117
| package | source | about |
1218
| ----- | ------ | ------ |
1319
| [siuba] | [github][sb-code] | Data analysis library. |
1420
| [shiny][shiny] | | Dashboarding framework. |
1521
| [vetiver][vetiver] | [github][vt-code] | A tool to version, share, deploy and monitor ML models. |
22+
| pins | | |
23+
| shinyswatch | | |
24+
| tiledb | | |
25+
1626

1727
: {tbl-colwidths="[20, 20, 60]"}
1828

29+
https://tiledb-inc.github.io/TileDB-Vector-Search/documentation/reference/
30+
1931
[pkgdown]: /examples/pkgdown/reference
2032
[pkgdown-code]: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
2133
[single-page]: /examples/single-page/reference
@@ -24,4 +36,86 @@
2436
[vetiver]: https://rstudio.github.io/vetiver-python/stable/reference/
2537
[vt-code]: https://github.com/rstudio/vetiver-python
2638
[siuba]: https://siuba.org/api/
27-
[sb-code]: https://github.com/machow/siuba.org
39+
[sb-code]: https://github.com/machow/siuba.org
40+
41+
:::::
42+
43+
44+
```{python}
45+
#| output: asis
46+
#| echo: false
47+
48+
def gallery(entries):
49+
combined = "\n\n".join(entries)
50+
51+
return f":::::: {{.gallery .list .grid}}\n{combined}\n::::::"
52+
53+
54+
def gallery_entry(src_thumbnail: str, href: str, title: str, href_ref=None, href_source=None):
55+
href_ref = href if href_ref is None else href_ref
56+
href_source = href if href_source is None else href_source
57+
58+
return f"""
59+
<div class="card border-2 rounded-3 g-col-12 g-col-sm-6 g-col-md-4 mb-2">
60+
<a href="{href}">
61+
<div class="card-header py-1 px-2 border-bottom border-1 bg-light">
62+
<p>{title}</p>
63+
</div>
64+
<div class="gallery-card-body">
65+
<img src="{src_thumbnail}">
66+
</div>
67+
<ul class="gallery-links">
68+
<li>
69+
<a class="view-reference" href="{href_ref}">Reference Page</a>
70+
</li>
71+
<li>
72+
<a class="view-source" href="{href_source}">Source</a>
73+
</li>
74+
</ul>
75+
</a>
76+
</div>
77+
"""
78+
79+
print(
80+
gallery([
81+
gallery_entry(
82+
"images/siuba-home.png",
83+
"https://siuba.org",
84+
"Siuba",
85+
href_ref = "https://siuba.org/api",
86+
href_source = "https://github.com/machow/siuba.org",
87+
),
88+
gallery_entry(
89+
"images/pins-home.png",
90+
"https://rstudio.github.io/pins-python",
91+
"Pins",
92+
href_ref = "https://rstudio.github.io/pins-python/reference",
93+
href_source = "http://github.com/rstudio/pins-python",
94+
),
95+
gallery_entry(
96+
"images/vetiver-home.png",
97+
"https://rstudio.github.io/vetiver-python",
98+
"Vetiver",
99+
href_ref = "https://rstudio.github.io/vetiver-python/stable/reference",
100+
href_source = "https://github.com/rstudio/vetiver-python",
101+
),
102+
gallery_entry(
103+
"images/shiny-home.png",
104+
"https://shiny.rstudio.com/py/",
105+
"Shiny",
106+
href_ref = "https://shiny.rstudio.com/py/api",
107+
href_source = "https://github.com/rstudio/py-shiny",
108+
),
109+
gallery_entry(
110+
"images/shinyswatch-home.png",
111+
"https://rstudio.github.io/py-shinyswatch/",
112+
"Shinyswatch",
113+
href_ref = "https://rstudio.github.io/py-shinyswatch/reference",
114+
href_source = "https://github.com/rstudio/py-shinyswatch",
115+
),
116+
])
117+
)
118+
```
119+
120+
121+
::::::

‎docs/get-started/overview.qmd‎

Lines changed: 11 additions & 7 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

‎docs/styles.css‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,36 @@ 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+
}
72+
73+
.gallery .gallery-card-body img {
74+
width: 100%;
75+
height: 100%;
76+
object-fit: contain;
77+
}
78+
79+
.gallery .card-header {
80+
font-size: 14px;
81+
text-decoration: none;
82+
text-align: center;
83+
}
84+
85+
.gallery .card-header a {
86+
text-decoration: none;
87+
}
88+
89+
.gallery-links ul {
90+
list-style-type: none;
91+
}
92+
93+
.gallery-links li {
94+
display: inline;
95+
margin-right: 60px;
96+
97+
}

‎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)