more doc updates
Jan Petykiewicz
4 years ago
parent
7d8901539c
commit
6e3cc1c3bd
@ -1,3 +1,15 @@
|
|||||||
#!/bin/bash
|
#!/bin/bash
|
||||||
cd ~/projects/meanas
|
cd ~/projects/meanas
|
||||||
pdoc3 --html --force --template-dir pdoc_templates -o doc .
|
|
||||||
|
# Approach 1: pdf to html?
|
||||||
|
#pdoc3 --pdf --force --template-dir pdoc_templates -o doc . | \
|
||||||
|
# pandoc --metadata=title:"meanas" --toc --toc-depth=4 --from=markdown+abbreviations --to=html --output=doc.html --gladtex -s -
|
||||||
|
|
||||||
|
# Approach 2: pdf to html with gladtex
|
||||||
|
pdoc3 --pdf --force --template-dir pdoc_templates -o doc . > doc.md
|
||||||
|
pandoc --metadata=title:"meanas" --from=markdown+abbreviations --to=html --output=doc.html --gladtex -s --css pdoc_templates/pdoc.css doc.md
|
||||||
|
gladtex -a -n -d _doc_mathimg -c white doc.html
|
||||||
|
|
||||||
|
# Approach 3: html with gladtex
|
||||||
|
#pdoc3 --html --force --template-dir pdoc_templates -o doc .
|
||||||
|
#find doc -iname '*.html' -exec gladtex -a -n -d _mathimg -c white {} \;
|
||||||
|
|||||||
@ -0,0 +1,185 @@
|
|||||||
|
<%!
|
||||||
|
import re
|
||||||
|
import pdoc
|
||||||
|
from pdoc.html_helpers import to_markdown, format_git_link
|
||||||
|
|
||||||
|
def link(d, fmt='{}'):
|
||||||
|
name = fmt.format(d.qualname + ('()' if isinstance(d, pdoc.Function) else ''))
|
||||||
|
if isinstance(d, pdoc.External):
|
||||||
|
return name
|
||||||
|
return '[{}](#{})'.format(name, d.refname)
|
||||||
|
|
||||||
|
def _to_md(text, module):
|
||||||
|
text = to_markdown(text, module=module, link=link)
|
||||||
|
# Setext H2 headings to atx H2 headings
|
||||||
|
text = re.sub(r'\n(.+)\n-{3,}\n', r'\n## \1\n\n', text)
|
||||||
|
# Convert admonitions into simpler paragraphs, dedent contents
|
||||||
|
text = re.sub(r'^(?P<indent>( *))!!! \w+ \"([^\"]*)\"(.*(?:\n(?P=indent) +.*)*)',
|
||||||
|
lambda m: '{}**{}:** {}'.format(m.group(2), m.group(3),
|
||||||
|
re.sub('\n {,4}', '\n', m.group(4))),
|
||||||
|
text, flags=re.MULTILINE)
|
||||||
|
return text
|
||||||
|
|
||||||
|
def subh(text, level=2):
|
||||||
|
# Deepen heading levels so H2 becomes H4 etc.
|
||||||
|
return re.sub(r'\n(#+) +(.+)\n', r'\n%s\1 \2\n' % ('#' * level), text)
|
||||||
|
%>
|
||||||
|
|
||||||
|
<%def name="title(level, string, id=None)">
|
||||||
|
<% id = ' {#%s}' % id if id is not None else '' %>
|
||||||
|
${('#' * level) + ' ' + string + id}
|
||||||
|
</%def>
|
||||||
|
|
||||||
|
<%def name="funcdef(f)">
|
||||||
|
<%
|
||||||
|
returns = show_type_annotations and f.return_annotation() or ''
|
||||||
|
if returns:
|
||||||
|
returns = ' -> ' + returns
|
||||||
|
%>
|
||||||
|
> `${f.funcdef()} ${f.name}(${', '.join(f.params(annotate=show_type_annotations))})${returns}`
|
||||||
|
</%def>
|
||||||
|
|
||||||
|
<%def name="classdef(c)">
|
||||||
|
> `class ${c.name}(${', '.join(c.params(annotate=show_type_annotations))})`
|
||||||
|
</%def>
|
||||||
|
|
||||||
|
<%def name="show_source(d)">
|
||||||
|
% if (show_source_code or git_link_template) and d.source and d.obj is not getattr(d.inherits, 'obj', None):
|
||||||
|
<% git_link = format_git_link(git_link_template, d) %>
|
||||||
|
[[view code]](${git_link})
|
||||||
|
%endif
|
||||||
|
</%def>
|
||||||
|
|
||||||
|
---
|
||||||
|
description: |
|
||||||
|
API documentation for modules: ${', '.join(m.name for m in modules)}.
|
||||||
|
|
||||||
|
lang: en
|
||||||
|
|
||||||
|
classoption: oneside
|
||||||
|
geometry: margin=1in
|
||||||
|
papersize: a4
|
||||||
|
|
||||||
|
linkcolor: blue
|
||||||
|
links-as-notes: true
|
||||||
|
...
|
||||||
|
% for module in modules:
|
||||||
|
<%
|
||||||
|
submodules = module.submodules()
|
||||||
|
variables = module.variables()
|
||||||
|
functions = module.functions()
|
||||||
|
classes = module.classes()
|
||||||
|
|
||||||
|
def to_md(text):
|
||||||
|
return _to_md(text, module)
|
||||||
|
%>
|
||||||
|
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
${title(1, ('Namespace' if module.is_namespace else 'Module') + ' `%s`' % module.name, module.refname)}
|
||||||
|
${module.docstring | to_md}
|
||||||
|
|
||||||
|
% if submodules:
|
||||||
|
${title(2, 'Sub-modules')}
|
||||||
|
% for m in submodules:
|
||||||
|
* [${m.name}](#${m.refname})
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if variables:
|
||||||
|
${title(2, 'Variables')}
|
||||||
|
% for v in variables:
|
||||||
|
${title(3, 'Variable `%s`' % v.name, v.refname)}
|
||||||
|
${show_source(v)}
|
||||||
|
${v.docstring | to_md, subh, subh}
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if functions:
|
||||||
|
${title(2, 'Functions')}
|
||||||
|
% for f in functions:
|
||||||
|
${title(3, 'Function `%s`' % f.name, f.refname)}
|
||||||
|
${show_source(f)}
|
||||||
|
|
||||||
|
${funcdef(f)}
|
||||||
|
|
||||||
|
${f.docstring | to_md, subh, subh}
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if classes:
|
||||||
|
${title(2, 'Classes')}
|
||||||
|
% for cls in classes:
|
||||||
|
${title(3, 'Class `%s`' % cls.name, cls.refname)}
|
||||||
|
${show_source(cls)}
|
||||||
|
|
||||||
|
${classdef(cls)}
|
||||||
|
|
||||||
|
${cls.docstring | to_md, subh}
|
||||||
|
<%
|
||||||
|
class_vars = cls.class_variables(show_inherited_members, sort=sort_identifiers)
|
||||||
|
static_methods = cls.functions(show_inherited_members, sort=sort_identifiers)
|
||||||
|
inst_vars = cls.instance_variables(show_inherited_members, sort=sort_identifiers)
|
||||||
|
methods = cls.methods(show_inherited_members, sort=sort_identifiers)
|
||||||
|
mro = cls.mro()
|
||||||
|
subclasses = cls.subclasses()
|
||||||
|
%>
|
||||||
|
% if mro:
|
||||||
|
${title(4, 'Ancestors (in MRO)')}
|
||||||
|
% for c in mro:
|
||||||
|
* [${c.refname}](#${c.refname})
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if subclasses:
|
||||||
|
${title(4, 'Descendants')}
|
||||||
|
% for c in subclasses:
|
||||||
|
* [${c.refname}](#${c.refname})
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if class_vars:
|
||||||
|
${title(4, 'Class variables')}
|
||||||
|
% for v in class_vars:
|
||||||
|
${title(5, 'Variable `%s`' % v.name, v.refname)}
|
||||||
|
${v.docstring | to_md, subh, subh}
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if inst_vars:
|
||||||
|
${title(4, 'Instance variables')}
|
||||||
|
% for v in inst_vars:
|
||||||
|
${title(5, 'Variable `%s`' % v.name, v.refname)}
|
||||||
|
${v.docstring | to_md, subh, subh}
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if static_methods:
|
||||||
|
${title(4, 'Static methods')}
|
||||||
|
% for f in static_methods:
|
||||||
|
${title(5, '`Method %s`' % f.name, f.refname)}
|
||||||
|
|
||||||
|
${funcdef(f)}
|
||||||
|
|
||||||
|
${f.docstring | to_md, subh, subh}
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
% if methods:
|
||||||
|
${title(4, 'Methods')}
|
||||||
|
% for f in methods:
|
||||||
|
${title(5, 'Method `%s`' % f.name, f.refname)}
|
||||||
|
|
||||||
|
${funcdef(f)}
|
||||||
|
|
||||||
|
${f.docstring | to_md, subh, subh}
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
% endfor
|
||||||
|
% endif
|
||||||
|
|
||||||
|
##\## for module in modules:
|
||||||
|
% endfor
|
||||||
|
|
||||||
|
-----
|
||||||
|
Generated by *pdoc* ${pdoc.__version__} (<https://pdoc3.github.io>).
|
||||||
@ -0,0 +1,381 @@
|
|||||||
|
.flex {
|
||||||
|
display: flex !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
body {
|
||||||
|
line-height: 1.5em;
|
||||||
|
background: black;
|
||||||
|
color: #DDD;
|
||||||
|
max-width: 140ch;
|
||||||
|
}
|
||||||
|
|
||||||
|
#content {
|
||||||
|
padding: 20px;
|
||||||
|
}
|
||||||
|
|
||||||
|
#sidebar {
|
||||||
|
padding: 30px;
|
||||||
|
overflow: hidden;
|
||||||
|
}
|
||||||
|
|
||||||
|
.http-server-breadcrumbs {
|
||||||
|
font-size: 130%;
|
||||||
|
margin: 0 0 15px 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
#footer {
|
||||||
|
font-size: .75em;
|
||||||
|
padding: 5px 30px;
|
||||||
|
border-top: 1px solid #ddd;
|
||||||
|
text-align: right;
|
||||||
|
}
|
||||||
|
#footer p {
|
||||||
|
margin: 0 0 0 1em;
|
||||||
|
display: inline-block;
|
||||||
|
}
|
||||||
|
#footer p:last-child {
|
||||||
|
margin-right: 30px;
|
||||||
|
}
|
||||||
|
|
||||||
|
h1, h2, h3, h4, h5 {
|
||||||
|
font-weight: 300;
|
||||||
|
}
|
||||||
|
h1 {
|
||||||
|
font-size: 2.5em;
|
||||||
|
line-height: 1.1em;
|
||||||
|
border-top: 20px white;
|
||||||
|
}
|
||||||
|
h2 {
|
||||||
|
font-size: 1.75em;
|
||||||
|
margin: 1em 0 .50em 0;
|
||||||
|
}
|
||||||
|
h3 {
|
||||||
|
font-size: 1.4em;
|
||||||
|
margin: 25px 0 10px 0;
|
||||||
|
}
|
||||||
|
h4 {
|
||||||
|
margin: 0;
|
||||||
|
font-size: 105%;
|
||||||
|
}
|
||||||
|
|
||||||
|
a {
|
||||||
|
color: #999;
|
||||||
|
text-decoration: none;
|
||||||
|
transition: color .3s ease-in-out;
|
||||||
|
}
|
||||||
|
a:hover {
|
||||||
|
color: #18d;
|
||||||
|
}
|
||||||
|
|
||||||
|
.title code {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
h2[id^="header-"] {
|
||||||
|
margin-top: 2em;
|
||||||
|
}
|
||||||
|
.ident {
|
||||||
|
color: #7ff;
|
||||||
|
}
|
||||||
|
|
||||||
|
pre code {
|
||||||
|
background: transparent;
|
||||||
|
font-size: .8em;
|
||||||
|
line-height: 1.4em;
|
||||||
|
}
|
||||||
|
code {
|
||||||
|
background: #0d0d0e;
|
||||||
|
padding: 1px 4px;
|
||||||
|
overflow-wrap: break-word;
|
||||||
|
}
|
||||||
|
h1 code { background: transparent }
|
||||||
|
|
||||||
|
pre {
|
||||||
|
background: #111;
|
||||||
|
border: 0;
|
||||||
|
border-top: 1px solid #ccc;
|
||||||
|
border-bottom: 1px solid #ccc;
|
||||||
|
margin: 1em 0;
|
||||||
|
padding: 1ex;
|
||||||
|
}
|
||||||
|
|
||||||
|
#http-server-module-list {
|
||||||
|
display: flex;
|
||||||
|
flex-flow: column;
|
||||||
|
}
|
||||||
|
#http-server-module-list div {
|
||||||
|
display: flex;
|
||||||
|
}
|
||||||
|
#http-server-module-list dt {
|
||||||
|
min-width: 10%;
|
||||||
|
}
|
||||||
|
#http-server-module-list p {
|
||||||
|
margin-top: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.toc ul,
|
||||||
|
#index {
|
||||||
|
list-style-type: none;
|
||||||
|
margin: 0;
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
#index code {
|
||||||
|
background: transparent;
|
||||||
|
}
|
||||||
|
#index h3 {
|
||||||
|
border-bottom: 1px solid #ddd;
|
||||||
|
}
|
||||||
|
#index ul {
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
#index h4 {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
#index h4 + ul {
|
||||||
|
margin-bottom:.6em;
|
||||||
|
}
|
||||||
|
/* Make TOC lists have 2+ columns when viewport is wide enough.
|
||||||
|
Assuming ~20-character identifiers and ~30% wide sidebar. */
|
||||||
|
@media (min-width: 200ex) { #index .two-column { column-count: 2 } }
|
||||||
|
@media (min-width: 300ex) { #index .two-column { column-count: 3 } }
|
||||||
|
|
||||||
|
dl {
|
||||||
|
margin-bottom: 2em;
|
||||||
|
}
|
||||||
|
dl dl:last-child {
|
||||||
|
margin-bottom: 4em;
|
||||||
|
}
|
||||||
|
dd {
|
||||||
|
margin: 0 0 1em 3em;
|
||||||
|
}
|
||||||
|
#header-classes + dl > dd {
|
||||||
|
margin-bottom: 3em;
|
||||||
|
}
|
||||||
|
dd dd {
|
||||||
|
margin-left: 2em;
|
||||||
|
}
|
||||||
|
dd p {
|
||||||
|
margin: 10px 0;
|
||||||
|
}
|
||||||
|
blockquote code {
|
||||||
|
background: #111;
|
||||||
|
font-weight: bold;
|
||||||
|
font-size: .85em;
|
||||||
|
padding: 5px 10px;
|
||||||
|
display: inline-block;
|
||||||
|
min-width: 40%;
|
||||||
|
}
|
||||||
|
blockquote code:hover {
|
||||||
|
background: #101010;
|
||||||
|
}
|
||||||
|
.name > span:first-child {
|
||||||
|
white-space: nowrap;
|
||||||
|
}
|
||||||
|
.name.class > span:nth-child(2) {
|
||||||
|
margin-left: .4em;
|
||||||
|
}
|
||||||
|
.inherited {
|
||||||
|
color: #777;
|
||||||
|
border-left: 5px solid #eee;
|
||||||
|
padding-left: 1em;
|
||||||
|
}
|
||||||
|
.inheritance em {
|
||||||
|
font-style: normal;
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Docstrings titles, e.g. in numpydoc format */
|
||||||
|
.desc h2 {
|
||||||
|
font-weight: 400;
|
||||||
|
font-size: 1.25em;
|
||||||
|
}
|
||||||
|
.desc h3 {
|
||||||
|
font-size: 1em;
|
||||||
|
}
|
||||||
|
.desc dt code {
|
||||||
|
background: inherit; /* Don't grey-back parameters */
|
||||||
|
}
|
||||||
|
|
||||||
|
.source summary,
|
||||||
|
.git-link-div {
|
||||||
|
color: #aaa;
|
||||||
|
text-align: right;
|
||||||
|
font-weight: 400;
|
||||||
|
font-size: .8em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
}
|
||||||
|
.source summary > * {
|
||||||
|
white-space: nowrap;
|
||||||
|
cursor: pointer;
|
||||||
|
}
|
||||||
|
.git-link {
|
||||||
|
color: inherit;
|
||||||
|
margin-left: 1em;
|
||||||
|
}
|
||||||
|
.source pre {
|
||||||
|
max-height: 500px;
|
||||||
|
overflow: auto;
|
||||||
|
margin: 0;
|
||||||
|
}
|
||||||
|
.source pre code {
|
||||||
|
font-size: 12px;
|
||||||
|
overflow: visible;
|
||||||
|
}
|
||||||
|
.hlist {
|
||||||
|
list-style: none;
|
||||||
|
}
|
||||||
|
.hlist li {
|
||||||
|
display: inline;
|
||||||
|
}
|
||||||
|
.hlist li:after {
|
||||||
|
content: ',\2002';
|
||||||
|
}
|
||||||
|
.hlist li:last-child:after {
|
||||||
|
content: none;
|
||||||
|
}
|
||||||
|
.hlist .hlist {
|
||||||
|
display: inline;
|
||||||
|
padding-left: 1em;
|
||||||
|
}
|
||||||
|
|
||||||
|
img {
|
||||||
|
max-width: 100%;
|
||||||
|
}
|
||||||
|
|
||||||
|
.admonition {
|
||||||
|
padding: .1em .5em;
|
||||||
|
margin-bottom: 1em;
|
||||||
|
}
|
||||||
|
.admonition-title {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
.admonition.note,
|
||||||
|
.admonition.info,
|
||||||
|
.admonition.important {
|
||||||
|
background: #610;
|
||||||
|
}
|
||||||
|
.admonition.todo,
|
||||||
|
.admonition.versionadded,
|
||||||
|
.admonition.tip,
|
||||||
|
.admonition.hint {
|
||||||
|
background: #202;
|
||||||
|
}
|
||||||
|
.admonition.warning,
|
||||||
|
.admonition.versionchanged,
|
||||||
|
.admonition.deprecated {
|
||||||
|
background: #02b;
|
||||||
|
}
|
||||||
|
.admonition.error,
|
||||||
|
.admonition.danger,
|
||||||
|
.admonition.caution {
|
||||||
|
background: darkpink;
|
||||||
|
}
|
||||||
|
|
||||||
|
@media screen and (min-width: 700px) {
|
||||||
|
#sidebar {
|
||||||
|
width: 30%;
|
||||||
|
}
|
||||||
|
#content {
|
||||||
|
width: 70%;
|
||||||
|
max-width: 100ch;
|
||||||
|
padding: 3em 4em;
|
||||||
|
border-left: 1px solid #ddd;
|
||||||
|
}
|
||||||
|
pre code {
|
||||||
|
font-size: 1em;
|
||||||
|
}
|
||||||
|
.item .name {
|
||||||
|
font-size: 1em;
|
||||||
|
}
|
||||||
|
main {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: row-reverse;
|
||||||
|
justify-content: flex-end;
|
||||||
|
}
|
||||||
|
.toc ul ul,
|
||||||
|
#index ul {
|
||||||
|
padding-left: 1.5em;
|
||||||
|
}
|
||||||
|
.toc > ul > li {
|
||||||
|
margin-top: .5em;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@media print {
|
||||||
|
#sidebar h1 {
|
||||||
|
page-break-before: always;
|
||||||
|
}
|
||||||
|
.source {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
@media print {
|
||||||
|
* {
|
||||||
|
background: transparent !important;
|
||||||
|
color: #000 !important; /* Black prints faster: h5bp.com/s */
|
||||||
|
box-shadow: none !important;
|
||||||
|
text-shadow: none !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
a[href]:after {
|
||||||
|
content: " (" attr(href) ")";
|
||||||
|
font-size: 90%;
|
||||||
|
}
|
||||||
|
/* Internal, documentation links, recognized by having a title,
|
||||||
|
don't need the URL explicity stated. */
|
||||||
|
a[href][title]:after {
|
||||||
|
content: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
abbr[title]:after {
|
||||||
|
content: " (" attr(title) ")";
|
||||||
|
}
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Don't show links for images, or javascript/internal links
|
||||||
|
*/
|
||||||
|
|
||||||
|
.ir a:after,
|
||||||
|
a[href^="javascript:"]:after,
|
||||||
|
a[href^="#"]:after {
|
||||||
|
content: "";
|
||||||
|
}
|
||||||
|
|
||||||
|
pre,
|
||||||
|
blockquote {
|
||||||
|
border: 1px solid #999;
|
||||||
|
page-break-inside: avoid;
|
||||||
|
}
|
||||||
|
|
||||||
|
thead {
|
||||||
|
display: table-header-group; /* h5bp.com/t */
|
||||||
|
}
|
||||||
|
|
||||||
|
tr,
|
||||||
|
img {
|
||||||
|
page-break-inside: avoid;
|
||||||
|
}
|
||||||
|
|
||||||
|
img {
|
||||||
|
max-width: 100% !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
@page {
|
||||||
|
margin: 0.5cm;
|
||||||
|
}
|
||||||
|
|
||||||
|
p,
|
||||||
|
h2,
|
||||||
|
h3 {
|
||||||
|
orphans: 3;
|
||||||
|
widows: 3;
|
||||||
|
}
|
||||||
|
|
||||||
|
h1,
|
||||||
|
h2,
|
||||||
|
h3,
|
||||||
|
h4,
|
||||||
|
h5,
|
||||||
|
h6 {
|
||||||
|
page-break-after: avoid;
|
||||||
|
}
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue