-
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Use Holocron to power its documentation
In order to eat our own dogfood and provide an always working example, let's use Holocron as a tool for building its own documentation.
- Loading branch information
1 parent
ea6c6bc
commit 791c17b
Showing
20 changed files
with
251 additions
and
760 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
metadata: | ||
title: Holocron | ||
url: https://ikalnytskyi.github.io/holocron | ||
|
||
pipes: | ||
build: | ||
- name: import-processors | ||
args: | ||
imports: | ||
- processors-docs = processors:process | ||
from_: "%(here)s/_plugins" | ||
|
||
- name: source | ||
args: | ||
pattern: "[^_.].*$" | ||
path: "%(here)s" | ||
|
||
- name: pipe | ||
args: | ||
pipe: | ||
- name: processors-docs | ||
- name: frontmatter | ||
- name: restructuredtext | ||
- name: jinja2 | ||
args: | ||
context: | ||
theme: | ||
navigation: !!pairs | ||
- Home: / | ||
- Processors: /processors/ | ||
- Pipes: /pipes/ | ||
|
||
ribbon: | ||
link: https://github.com/ikalnytskyi/holocron | ||
text: GitHub | ||
|
||
copyright: | | ||
© | ||
<a rel="me" href="https://github.com/ikalnytskyi/holocron/graphs/contributors"> | ||
the Holocron Team | ||
</a> | ||
when: | ||
- item.source.match("*.rst") | ||
|
||
- name: save | ||
args: | ||
to: "%(here)s/_site" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
"""Inspect Holocron sources and inject documentation.""" | ||
|
||
import inspect | ||
import re | ||
|
||
|
||
class _MarkupInjector: | ||
"""Replace <!-- inject: something --> with content.""" | ||
|
||
_re_injections_format = r"..\s+inject:\s+%s\s+" | ||
_re_injections = { | ||
"processors-docs": "processors_docs", | ||
} | ||
|
||
def __init__(self, processors): | ||
self._processors = processors | ||
self._re_injections = { | ||
re.compile(self._re_injections_format % point): getattr(self, property_) | ||
for point, property_ in self._re_injections.items() | ||
} | ||
|
||
def process(self, content): | ||
for regex, injection in self._re_injections.items(): | ||
content = regex.sub(injection, content) | ||
return content | ||
|
||
@property | ||
def processors_docs(self): | ||
processors_docs = [] | ||
|
||
for name, processor in self._processors.items(): | ||
anchor = f".. _{name}:" | ||
ref_name = f"`{name}`_" | ||
|
||
processor_docs = [ | ||
anchor, | ||
"", | ||
ref_name, | ||
"-" * len(ref_name), | ||
"", | ||
inspect.getdoc(processor) or "", | ||
] | ||
processors_docs.append("\n".join(processor_docs)) | ||
|
||
return "\n\n".join(processors_docs) | ||
|
||
|
||
def process(app, stream, *, exceptions=None): | ||
injector = _MarkupInjector( | ||
{ | ||
name: processor | ||
for name, processor in app._processors.items() | ||
if processor.__module__.startswith("holocron") | ||
} | ||
) | ||
|
||
for item in stream: | ||
item["content"] = injector.process(item["content"]) | ||
yield item |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.