Skip to content

Commit f5220e5

Browse files
rgaudinrgaudin
committed
added initial mkdocs
1 parent 152e89a commit f5220e5

File tree

6 files changed

+228
-0
lines changed

6 files changed

+228
-0
lines changed

‎docs/assets/openzim.png‎

9.69 KB
Loading

‎docs/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: libzim Documentation
3+
---
4+
5+
{%
6+
include-markdown "../README.md"
7+
%}

‎docs/license.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: License
3+
---
4+
5+
```
6+
--8<-- "LICENSE"
7+
```

‎docs/scripts/generate_api_nav.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
"""
2+
Script called by mkdocs-gen-files that generates markdown documents
3+
with API reference placeholders.
4+
5+
https://oprypin.github.io/mkdocs-gen-files/api.html
6+
"""
7+
8+
from pathlib import Path
9+
10+
import mkdocs_gen_files
11+
12+
nav = mkdocs_gen_files.Nav()
13+
14+
root = Path(__file__).parent.parent.parent
15+
src = root / "libzim"
16+
api_reference = Path("api_reference")
17+
18+
for path in sorted(src.rglob("*.pyi")):
19+
module_path = path.relative_to(root).with_suffix("")
20+
21+
# Package docs get the parent module name.
22+
if module_path.name == "__init__":
23+
module_path = module_path.parent
24+
elif module_path.name.startswith("_"):
25+
# Skip other hidden items
26+
continue
27+
identifier = ".".join(module_path.parts)
28+
29+
doc_path = identifier + ".md"
30+
full_doc_path = api_reference / doc_path
31+
print(f"{full_doc_path=}")
32+
33+
nav[identifier] = doc_path
34+
35+
# Create a document with mkdocstrings placeholders.
36+
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
37+
fd.write(f"""---
38+
title: {identifier}
39+
---
40+
41+
::: {identifier}
42+
""")
43+
44+
# Make the edit button on the page link to the source file.
45+
mkdocs_gen_files.set_edit_path(full_doc_path, Path("..") / path.relative_to(root))
46+
47+
# Write a navigation file that will be interpreted by literate-nav.
48+
with mkdocs_gen_files.open(api_reference / "NAVIGATION.md", "w") as fd:
49+
fd.writelines(nav.build_literate_nav())

‎mkdocs.yml‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
site_name: libzim
2+
site_description: 'XX.'
3+
repo_url: https://github.com/openzim/python-libzim
4+
repo_name: GitHub
5+
edit_uri: edit/main/docs/
6+
7+
validation:
8+
omitted_files: warn
9+
absolute_links: warn
10+
unrecognized_links: warn
11+
12+
nav:
13+
- Home: index.md
14+
- API Reference: api_reference/
15+
- License: license.md
16+
17+
theme:
18+
name: material
19+
logo: assets/openzim.png
20+
palette:
21+
# Light mode
22+
- scheme: default
23+
toggle:
24+
icon: material/brightness-7
25+
name: Switch to dark mode
26+
# Dark mode
27+
- scheme: slate
28+
toggle:
29+
icon: material/brightness-4
30+
name: Switch to light mode
31+
features:
32+
# Use XHR for page changes to avoid page flash during navigation.
33+
- navigation.instant
34+
- navigation.instant.progress
35+
# Use tabs and section headers rather than a single side navbar.
36+
- navigation.tabs
37+
- navigation.sections
38+
# Add buttons to edit content
39+
- content.action.edit
40+
- content.code.annotate
41+
- content.code.copy
42+
- content.tooltips
43+
- navigation.expand
44+
- navigation.footer
45+
- navigation.path
46+
- navigation.sections
47+
- navigation.tabs
48+
- navigation.tabs.sticky
49+
- navigation.top
50+
- search.highlight
51+
- search.suggest
52+
- toc.follow
53+
54+
extra_css:
55+
- assets/mkdocstrings.css
56+
57+
markdown_extensions:
58+
- attr_list
59+
- admonition
60+
- callouts:
61+
strip_period: no
62+
- footnotes
63+
- md_in_html
64+
- pymdownx.blocks.tab:
65+
alternate_style: true
66+
- pymdownx.snippets:
67+
base_path: .
68+
check_paths: true
69+
- pymdownx.superfences:
70+
custom_fences:
71+
- name: mermaid
72+
class: mermaid
73+
format: !!python/name:pymdownx.superfences.fence_code_format
74+
- pymdownx.tabbed:
75+
alternate_style: true
76+
slugify: !!python/object/apply:pymdownx.slugs.slugify
77+
kwds:
78+
case: lower
79+
- pymdownx.tasklist:
80+
custom_checkbox: true
81+
- toc:
82+
permalink: "¤"
83+
84+
plugins:
85+
- search
86+
- markdown-exec:
87+
ansi: required
88+
89+
# Replace externally hosted assets for compliance with various privacy regulations.
90+
- privacy
91+
92+
# Nicely include markdown, e.g. to rewrite relative links
93+
- include-markdown
94+
95+
# Generate API docs and navigation for them
96+
- gen-files:
97+
scripts:
98+
- gen_griffe_json.py
99+
- docs/scripts/generate_api_nav.py
100+
101+
# Import additional nav from NAVIGATION.md files, like the one produced
102+
# by gen-files.
103+
- literate-nav:
104+
nav_file: NAVIGATION.md
105+
106+
# Generate items
107+
- mkdocstrings:
108+
handlers:
109+
python:
110+
# Set up cross-references to Python types
111+
import:
112+
- url: https://docs.python.org/3/objects.inv
113+
domains: [std, py]
114+
- https://typing-extensions.readthedocs.io/en/latest/objects.inv
115+
paths: [libzim]
116+
options:
117+
load_external_modules: false
118+
allow_inspection: true
119+
force_inspection: true
120+
show_source: false
121+
docstring_section_style: list
122+
docstring_style: google
123+
filters:
124+
# attr and methods starting with _
125+
- '!^_'
126+
# *_module_* for internal libzim-only vars that build the sub modules
127+
- '!_module_'
128+
# *_public_objects for internal libzim-only vars that exposes sub modules
129+
- '!_public_objects$'
130+
show_submodules: false
131+
inherited_members: true
132+
separate_signature: true
133+
show_signature_annotations: true
134+
show_symbol_type_heading: true
135+
show_symbol_type_toc: true
136+
signature_crossrefs: true
137+
summary: true
138+
show_if_no_docstring: true
139+
modernize_annotations: true

‎pyproject.toml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,31 @@ build = [
7373
"cython == 3.0.11",
7474
"delocate == 0.11.0 ; platform_system=='Windows'",
7575
]
76+
doc = [
77+
78+
"mkdocs==1.6.1",
79+
"mkdocstrings[python]==0.27.0",
80+
"mkdocs-material==9.5.44",
81+
"pymdown-extensions==10.12",
82+
"mkdocs-gen-files==0.5.0",
83+
"mkdocs-literate-nav==0.6.1",
84+
"mkdocs-include-markdown-plugin==7.1.2",
85+
"griffe==1.5.5",
86+
87+
"black==24.10.0",
88+
"code2flow==2.5.1",
89+
"griffe-inherited-docstrings==1.1.1",
90+
"markdown-callouts==0.4.0",
91+
"markdown-exec[ansi]==1.10.0",
92+
"mkdocs-coverage==1.1.0",
93+
"mkdocs-git-revision-date-localized-plugin==1.3.0",
94+
"mkdocs-minify-plugin==0.8.0",
95+
"mkdocs-section-index==0.3.9",
96+
"mkdocs-redirects==1.2.2",
97+
"pydeps==3.0.0",
98+
# YORE: EOL 3.10: Remove line.
99+
"tomli==2.2.1; python_version < '3.11'",
100+
]
76101
dev = [
77102
"pre-commit==4.0.1",
78103
"ipython==8.28.0",
@@ -82,6 +107,7 @@ dev = [
82107
"libzim[test]",
83108
"libzim[check]",
84109
"libzim[build]",
110+
"libzim[doc]",
85111
]
86112

87113
[tool.setuptools]

0 commit comments

Comments
 (0)