Skip to content

Commit

Permalink
Use Holocron to power its documentation
Browse files Browse the repository at this point in the history
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
ikalnytskyi committed Oct 31, 2021
1 parent ea6c6bc commit 791c17b
Show file tree
Hide file tree
Showing 20 changed files with 251 additions and 760 deletions.
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ coverage.xml
*.mo

# Sphinx documentation
docs/_build/
docs/_site/

# Ignore sublime's project (for fans)
.ropeproject/
Expand Down
47 changes: 47 additions & 0 deletions docs/.holocron.yml
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"
59 changes: 59 additions & 0 deletions docs/_plugins/processors.py
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
22 changes: 0 additions & 22 deletions docs/_static/logo.svg

This file was deleted.

3 changes: 0 additions & 3 deletions docs/authors.rst

This file was deleted.

3 changes: 0 additions & 3 deletions docs/changes.rst

This file was deleted.

46 changes: 0 additions & 46 deletions docs/conf.py

This file was deleted.

3 changes: 0 additions & 3 deletions docs/contributing.rst

This file was deleted.

Loading

0 comments on commit 791c17b

Please sign in to comment.