Skip to content

Commit ae95a52

Browse files
machowmachow
authored
Merge pull request #11 from machow/docs-basic-site
docs: basic site
2 parents 5b1375c + cc9a3aa commit ae95a52

21 files changed

+695
-38
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ name: CI
33
on:
44
workflow_dispatch:
55
push:
6+
branches: ["main", "dev-*"]
67
pull_request:
78
release:
89
types: [published]
@@ -65,3 +66,74 @@ jobs:
6566
with:
6667
user: __token__
6768
password: ${{ secrets.PYPI_API_TOKEN }}
69+
70+
build-docs:
71+
runs-on: ubuntu-latest
72+
steps:
73+
- uses: actions/checkout@v2
74+
- uses: actions/setup-python@v2
75+
with:
76+
python-version: "3.9"
77+
- name: Install dependencies
78+
run: |
79+
python -m pip install -r requirements-dev.txt
80+
- uses: quarto-dev/quarto-actions/setup@v2
81+
- name: Build docs
82+
run: |
83+
make docs-build
84+
# push to netlify -------------------------------------------------------
85+
86+
# set release name ----
87+
88+
- name: Configure pull release name
89+
if: ${{github.event_name == 'pull_request'}}
90+
run: |
91+
echo "RELEASE_NAME=pr-${PR_NUMBER}" >> $GITHUB_ENV
92+
env:
93+
PR_NUMBER: ${{ github.event.number }}
94+
- name: Configure branch release name
95+
if: ${{github.event_name != 'pull_request'}}
96+
run: |
97+
# use branch name, but replace slashes. E.g. feat/a -> feat-a
98+
echo "RELEASE_NAME=${GITHUB_REF_NAME/\//-}" >> $GITHUB_ENV
99+
# deploy ----
100+
101+
- name: Create Github Deployment
102+
uses: bobheadxi/[email protected]
103+
id: deployment
104+
with:
105+
step: start
106+
token: ${{ secrets.GITHUB_TOKEN }}
107+
env: ${{ env.RELEASE_NAME }}
108+
ref: ${{ github.head_ref }}
109+
transient: true
110+
logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
111+
112+
- name: Netlify docs preview
113+
run: |
114+
npm install -g netlify-cli
115+
# push main branch to production, others to preview --
116+
if [ "${ALIAS}" == "main" ]; then
117+
netlify deploy --dir=docs/_build --alias="main"
118+
else
119+
netlify deploy --dir=docs/_build --alias="${ALIAS}"
120+
fi
121+
env:
122+
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
123+
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
124+
ALIAS: ${{ steps.deployment.outputs.env }}
125+
126+
- name: Update Github Deployment
127+
uses: bobheadxi/[email protected]
128+
if: ${{ always() }}
129+
with:
130+
step: finish
131+
token: ${{ secrets.GITHUB_TOKEN }}
132+
status: ${{ job.status }}
133+
deployment_id: ${{ steps.deployment.outputs.deployment_id }}
134+
env_url: 'https://${{ steps.deployment.outputs.env }}--quartodoc.netlify.app'
135+
logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
136+
- uses: peaceiris/actions-gh-pages@v3
137+
with:
138+
github_token: ${{ secrets.GITHUB_TOKEN }}
139+
publish_dir: docs/_build

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
# Notebooks ===================================================================
2+
*.ipynb
3+
14
# Mac OSX =====================================================================
25
.DS_Store
36

@@ -134,3 +137,7 @@ dmypy.json
134137

135138
# Pyre type checker
136139
.pyre/
140+
.Rproj.user
141+
142+
# Local Netlify folder
143+
.netlify

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
exclude: ".*\\.(csv)|(md)"
1+
exclude: ".*\\.(csv)|(md)|(json)"
22
repos:
33
- repo: https://github.com/pre-commit/pre-commit-hooks
44
rev: v2.4.0

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
11
README.md: README.qmd
22
quarto render $<
3+
4+
docs-build:
5+
quarto render docs

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/.quarto/
2+
_site

‎docs/1_generate_api.py‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
import sys
2+
3+
from pathlib import Path
4+
from quartodoc import (
5+
get_object,
6+
MdRenderer,
7+
create_inventory,
8+
convert_inventory,
9+
__version__,
10+
)
11+
12+
FUNCTIONS = [
13+
"get_object",
14+
"create_inventory",
15+
"convert_inventory",
16+
"MdRenderer",
17+
]
18+
19+
PACKAGE = "quartodoc"
20+
21+
# +
22+
root = Path(sys.argv[0]).parent
23+
renderer = MdRenderer(header_level=1)
24+
25+
p = root / "api"
26+
p.mkdir(exist_ok=True)
27+
# -
28+
29+
# Stage 1: inventory file ----
30+
all_objects = []
31+
for name in FUNCTIONS:
32+
all_objects.append(get_object(PACKAGE, name))
33+
34+
inv = create_inventory(
35+
PACKAGE,
36+
__version__,
37+
all_objects,
38+
uri=lambda s: f"api/#{s.name}",
39+
dispname=lambda s: f"{s.name}",
40+
)
41+
convert_inventory(inv, "objects.json")
42+
43+
# Stage 2: render api pages ----
44+
all_content = []
45+
for f_obj in all_objects:
46+
print(f_obj.name)
47+
content = renderer.to_md(f_obj)
48+
all_content.append(content)
49+
50+
# p_func = p / f"{f_obj.name}.md"
51+
# p_func.write_text(content)
52+
53+
(p / "index.md").write_text("\n\n".join(all_content))

‎docs/_quarto.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
project:
2+
type: website
3+
output-dir: _build
4+
resources:
5+
- objects.json
6+
7+
website:
8+
title: "quartodoc"
9+
navbar:
10+
left:
11+
- file: get-started/overview.qmd
12+
text: Get Started
13+
- href: api/
14+
text: Reference
15+
- about.qmd
16+
sidebar:
17+
- id: get-started
18+
title: Get Started
19+
style: floating
20+
align: left
21+
contents:
22+
- get-started/overview.qmd
23+
- get-started/docstrings.qmd
24+
- get-started/renderers.qmd
25+
- get-started/crossrefs.qmd
26+
- id: dummy
27+
28+
29+
format:
30+
html:
31+
theme: cosmo
32+
css: styles.css
33+
toc: true

‎docs/about.qmd‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "About"
3+
---
4+
5+
About this site

‎docs/api/index.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# get_object {#sec-get_object}
2+
3+
`get_object(module: str, object_name: str, parser: str = 'numpy')`
4+
5+
Fetch a griffe object.
6+
7+
## Parameters
8+
9+
| Name | Type | Description | Default |
10+
|---------------|--------|----------------------------|-----------|
11+
| `module` | str | A module name. | required |
12+
| `object_name` | str | A function name. | required |
13+
| `parser` | str | A docstring parser to use. | `'numpy'` |
14+
15+
See Also
16+
--------
17+
get_function: a deprecated function.
18+
19+
## Examples
20+
21+
```python
22+
>>> get_function("quartodoc", "get_function")
23+
<Function('get_function', ...
24+
```
25+
26+
# create_inventory {#sec-create_inventory}
27+
28+
`create_inventory(project: str, version: str, items: list[dc.Object | dc.Alias], uri: str | Callable[dc.Object, str] = <function <lambda> at 0x105878700>, dispname: str | Callable[dc.Object, str] = '-')`
29+
30+
Return a sphinx inventory file.
31+
32+
## Parameters
33+
34+
| Name | Type | Description | Default |
35+
|------------|--------------------------------|----------------------------------------------------------------|--------------------------------------|
36+
| `project` | str | Name of the project (often the package name). | required |
37+
| `version` | str | Version of the project (often the package version). | required |
38+
| `items` | list[dc.Object | dc.Alias] | A docstring parser to use. | required |
39+
| `uri` | str | Callable[dc.Object, str] | Link relative to the docs where the items documentation lives. | `<function <lambda> at 0x105878700>` |
40+
| `dispname` | str | Callable[dc.Object, str] | Name to be shown when a link to the item is made. | `'-'` |
41+
42+
## Examples
43+
44+
```python
45+
>>> f_obj = get_object("quartodoc", "create_inventory")
46+
>>> inv = create_inventory("example", "0.0", [f_obj])
47+
>>> inv
48+
Inventory(project='example', version='0.0', source_type=<SourceTypes.Manual: 'manual'>)
49+
```
50+
51+
To preview the inventory, we can convert it to a dictionary:
52+
53+
```python
54+
>>> _to_clean_dict(inv)
55+
{'project': 'example',
56+
'version': '0.0',
57+
'count': 1,
58+
'items': [{'name': 'quartodoc.create_inventory',
59+
'domain': 'py',
60+
'role': 'function',
61+
'priority': '1',
62+
'uri': 'quartodoc.create_inventory.html',
63+
'dispname': '-'}]}
64+
```
65+
66+
# convert_inventory {#sec-convert_inventory}
67+
68+
`convert_inventory(in_name: Union[str, soi.Inventory], out_name=None)`
69+
70+
Convert a sphinx inventory file to json.
71+
72+
## Parameters
73+
74+
| Name | Type | Description | Default |
75+
|------------|---------------------------|-------------------------|-----------|
76+
| `in_name` | Union[str, soi.Inventory] | Name of inventory file. | required |
77+
| `out_name` | | Output file name. | `None` |
78+
79+
# MdRenderer {#sec-MdRenderer}
80+
81+
`MdRenderer(self, header_level: int = 2, show_signature: bool = True, hook_pre=None)`
82+
83+
Render docstrings to markdown.
84+
85+
## Parameters
86+
87+
| Name | Type | Description | Default |
88+
|------------------|--------|--------------------------------------------------|-----------|
89+
| `header_level` | int | The level of the header (e.g. 1 is the biggest). | `2` |
90+
| `show_signature` | bool | Whether to show the function signature. | `True` |
91+
92+
## Examples
93+
94+
```python
95+
>>> from quartodoc import MdRenderer, get_object
96+
>>> renderer = MdRenderer(header_level=2)
97+
>>> f = get_object("quartodoc", "get_object")
98+
>>> print(renderer.to_md(f)[:81])
99+
## get_object
100+
`get_object(module: str, object_name: str, parser: str = 'numpy')`
101+
```

‎docs/get-started/crossrefs.qmd‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Cross references
3+
jupyter:
4+
kernelspec:
5+
display_name: Python 3 (ipykernel)
6+
language: python
7+
name: python3
8+
---
9+
10+
Coming soon!
11+
12+
## Link within a doc
13+
14+
* `@sec-get_object` doesn't seem to work: @sec-get-_object.
15+
* [get_object](/api/#sec-get_object)
16+
17+
## Link to external docs
18+
19+
### Inventory files
20+
21+
22+
## The "See Also" section
23+

0 commit comments

Comments
 (0)