def append_end(self, data):
"""Write at the last position of a Markdown file.
:param str data: is a string containing all the data that is written in the markdown file."""
with mkdocs_gen_files.open(self.file_name, 'a',
encoding='utf-8') as self.file:
self.file.write(data)
def rewrite_all_file(self, data):
"""Rewrite all the data of a Markdown file by ``data``.
:param str data: is a string containing all the data that is written in the markdown file."""
with mkdocs_gen_files.open(self.file_name, 'w',
encoding='utf-8') as self.file:
self.file.write(data)
def __init__(self, name=''):
"""Creates a markdown file, if name is not empty.
:param str name: file name"""
if name:
self.file_name = name if name.endswith('.md') else name + '.md'
self.file = mkdocs_gen_files.open(self.file_name,
'w+',
encoding='UTF-8')
self.file.close()
def write_file(abs_id, filename):
with mkdocs_gen_files.open(filename, 'w') as f:
# Write the entry of a top-level alias (e.g. `AED`) on the same page as the aliased item.
for root_typ in root.types:
if root_typ.kind == "alias":
if root_typ.aliased == abs_id:
f.write(f'::: {root_typ.abs_id}\n\n')
f.write(f'::: {abs_id}\n\n')
def append_after_second_line(self, data):
"""Write after the file's first line.
:param str data: is a string containing all the data that is written in the markdown file."""
with mkdocs_gen_files.open(self.file_name, 'r+',
encoding='utf-8') as self.file:
file_data = self.file.read() # Save all the file's content
self.file.seek(0, 0) # Place file pointer at the beginning
first_line = self.file.readline() # Read the first line
second_line = self.file.readline() # Read the second line
self.file.seek(
len(first_line + second_line),
0) # Place file pointer at the end of the first line
self.file.write(data) # Write data
self.file.write('\n' + file_data[len(first_line + second_line):])
def read_file(file_name):
"""Read a Markdown file using a file name. It is not necessary to add *.md extension.
:param file_name: Markdown file's name.
:type file_name: str
:return: return all file's data.
:rtype: str"""
if file_name.find('.md') == -1:
file_name += '.md'
with mkdocs_gen_files.open(file_name, 'r', encoding='utf-8') as file:
file_data = file.read()
return file_data
def main():
r"""
Create MarkDown files in a virtual file system that is consumed by mkdocs
when building the website.
This function is invoked automatically by mkdocs during the build process.
"""
for entry in website.generator.database.cv:
with mkdocs_gen_files.open(
os.path.join("cv", "entries", f"{entry.identifier}.md"), "w"
) as markdown:
markdown.write(
render(
"pages/cv_entry.md",
database=website.generator.database.cv,
entry=entry,
)
)
# Generates virtual doc files for the mkdocs site.
# You can also run this script directly to actually write out those files, as a preview.
import collections
import mkdocs_gen_files
root = mkdocs_gen_files.config['plugins']['mkdocstrings'].get_handler(
'crystal').collector.root
for typ in root.walk_types():
filename = 'api_reference/' + '/'.join(
typ.abs_id.split('::')) + '/index.md'
with mkdocs_gen_files.open(filename, 'w') as f:
f.write(f'# ::: {typ.abs_id}\n\n')
if typ.locations:
mkdocs_gen_files.set_edit_path(filename, typ.locations[0].url)
import mkdocs_gen_files
import os
import glob
# iterate over pages and append glossary
for file in glob.glob("/docs/docs/**/*.md", recursive=True):
if file.endswith('.md'):
text = open(file).read()
with mkdocs_gen_files.open(file.replace('/docs/docs/', ''), "w") as f:
print(text + '\n--8<-- "./glossary.md"', file=f)
#!/usr/bin/env python
from pathlib import Path
import mkdocs_gen_files
CODE_ROOT = "snoop"
with mkdocs_gen_files.open("module-index.md", 'w') as index:
print("# Module index\n", file=index)
for path in Path(CODE_ROOT).glob("**/*.py"):
doc_path = Path("reference", path.relative_to(".")).with_suffix(".md")
ident = ".".join(path.relative_to(".").with_suffix("").parts)
# skip database migraitons
if ident.startswith('snoop.data.migrations.'):
continue
# write file
with mkdocs_gen_files.open(doc_path, "w") as f:
print("::: " + ident, file=f)
# write entry in module index file
print(f"- [`{ident}`][{ident}]", file=index)
mkdocs_gen_files.set_edit_path(doc_path, Path('..', path))
from pathlib import Path
from os import sep as SLASH
import mkdocs_gen_files
src_root = Path("python_tooling_enterpy_2021")
api_doc_tree = []
for path in src_root.glob("**/*.py"):
doc_path = Path("api_doc", path.relative_to(src_root)).with_suffix(".md")
with mkdocs_gen_files.open(doc_path, "w") as f:
print("[TOC]", file=f)
ident = ".".join(path.with_suffix("").parts)
print("::: " + ident, file=f)
api_doc_tree.append(path.relative_to(src_root))
with mkdocs_gen_files.open("api_doc.md", "w") as f:
# assumes files in api_doc_tree to be ordered by directory
already_used = []
for doc_path in api_doc_tree:
markdown_file = Path(doc_path).with_suffix('.md')
levels = str(markdown_file).count(SLASH)
if levels <= 0 and src_root not in already_used:
print(f"{src_root}\n\n", file=f)
already_used.append(src_root)
elif levels >= 1:
file_path = str(markdown_file).split(SLASH)
directory_path = file_path[:-1]
module_name = file_path[levels - 1:levels][0]
if directory_path not in already_used:
print(f"{' ' * (levels - 1)}- {module_name}", file=f)
already_used.append(directory_path)
import mkdocs_gen_files
import os
# Move README to index unless there's already an index.md
if (os.path.exists("/docs/docs/index.md") != True):
readme = open("/docs/README.md").read()
with mkdocs_gen_files.open("index.md", "w") as f:
print(readme, file=f)
# Move CONTRIBUTING to developing
if (os.path.exists("/docs/CONTRIBUTING.md")):
readme = open("/docs/CONTRIBUTING.md").read()
with mkdocs_gen_files.open("contributing.md", "w") as f:
print(readme, file=f)
# Move Library Docs
rootdir = "/docs/libraries"
for library in os.listdir(rootdir):
file = os.path.join(rootdir, library, "README.md")
if (os.path.exists(file)):
readme = open(file).read()
with mkdocs_gen_files.open(f"libraries/{library}.md", "w") as f:
print(readme, file=f)
# Generate virtual doc files for the mkdocs site.
# You can also run this script directly to actually write out those files, as a preview.
import mkdocs_gen_files
# Get the documentation root object
root = mkdocs_gen_files.config["plugins"]["mkdocstrings"].get_handler("crystal").collector.root
# For each type (e.g. "Foo::Bar")
for typ in root.walk_types():
# Use the file name "Foo/Bar/index.md"
filename = "/".join(typ.abs_id.split("::") + ["index.md"])
# Make a file with the content "# ::: Foo::Bar\n"
with mkdocs_gen_files.open(filename, "w") as f:
print(f"# ::: {typ.abs_id}", file=f)
# Link to the type itself when clicking the "edit" button on the page.
if typ.locations:
mkdocs_gen_files.set_edit_path(filename, typ.locations[0].url)
#!/usr/bin/env python
from pathlib import Path
import mkdocs_gen_files
for path in Path("src", "mkdocstrings").glob("**/*.py"):
doc_path = Path("reference",
path.relative_to("src", "mkdocstrings")).with_suffix(".md")
with mkdocs_gen_files.open(doc_path, "w") as f:
ident = ".".join(path.relative_to("src").with_suffix("").parts)
print("::: " + ident, file=f)
mkdocs_gen_files.set_edit_path(doc_path, Path("..", path))
import mkdocs_gen_files
with mkdocs_gen_files.open("assets/style.css", "a") as f:
f.write(
"\n"
+ ",\n".join(
f".configurator > input:nth-of-type({i}):checked ~ div:not(.c{i}), "
f".configurator > input:nth-of-type({i}):not(:checked) ~ div.c{i}"
for i in range(1, 10)
)
+ " {\n display: none;\n}\n"
)
# Generate virtual doc files for the mkdocs site.
# You can also run this script directly to actually write out those files, as a preview.
import mkdocs_gen_files
# Get the documentation root object
root = mkdocs_gen_files.config['plugins']['mkdocstrings'].get_handler(
'crystal').collector.root
# Start a navigation file (to be filled as we go along)
nav = mkdocs_gen_files.open('SUMMARY.md', 'a')
# For each type (e.g. "Foo::Bar")
for typ in root.walk_types():
# Use the file name "Foo/Bar.md"
filename = '/'.join(typ.abs_id.split('::')) + '.md'
# Make a file with the content "# ::: Foo::Bar\n"
with mkdocs_gen_files.open(filename, 'w') as f:
print(f'# ::: {typ.abs_id}', file=f)
# Link to the type itself when clicking the "edit" button on the page
if typ.locations:
mkdocs_gen_files.set_edit_path(filename, typ.locations[0].url)
# Append to the nav: " * [Bar](Foo/Bar.md)"
indent = ' ' * typ.abs_id.count('::')
print(indent + f'* [{typ.name}]({filename})', file=nav)
def open(self, mode: str):
if self.mkdocs:
return mkdocs_gen_files.open(self.path, mode, encoding='UTF-8')
else:
return open(self.path, mode, encoding='UTF-8')
import mkdocs_gen_files
for total in range(19, 100, 20):
with mkdocs_gen_files.open(f"sample/{total}-bottles.md", "w") as f:
for i in reversed(range(1, total + 1)):
print(f"{i} bottles of beer on the wall, {i} bottles of beer ", file=f)
print(f"Take one down and pass it around, **{i-1}** bottles of beer on the wall\n", file=f)
# Generates virtual doc files for the mkdocs site.
# You can also run this script directly to actually write out those files, as a preview.
import mkdocs_gen_files
root = mkdocs_gen_files.config['plugins']['mkdocstrings'].get_handler(
'crystal').collector.root
for typ in root.lookup("ActionController").walk_types():
# ActionController::Router::RouteHandler -> Router/RouteHandler/index.md
filename = '/'.join(typ.abs_id.split('::')[1:] + ['index.md'])
with mkdocs_gen_files.open(filename, 'w') as f:
f.write(f'# ::: {typ.abs_id}\n\n')
if typ.locations:
mkdocs_gen_files.set_edit_path(filename, typ.locations[0].url)
for typ in root.types:
# Write the entry of a top-level alias (e.g. `AED`) to its appropriate section.
if typ.kind == "alias":
# ActionController::AC -> ActionController/aliases.md
filename = '/'.join([typ.aliased.split('::')[0], 'aliases.md'])
with mkdocs_gen_files.open(filename, 'a') as f:
f.write(f'::: {typ.abs_id}\n\n')
# Write the top level `ActionController` module to its appropriate section.
# ActionController -> Config/environment.md
with mkdocs_gen_files.open('Config/environment.md', 'w') as f:
f.write(f'# ::: ActionController\n\n')
}
indirect_dependencies -= direct_dependencies
return {
"project_name": project_name,
"direct_dependencies": sorted(direct_dependencies),
"indirect_dependencies": sorted(indirect_dependencies),
"more_credits": "http://pawamoy.github.io/credits/",
}
@functools.lru_cache(maxsize=None)
def get_credits():
"""Return credits as Markdown.
Returns:
The credits page Markdown.
"""
jinja_env = SandboxedEnvironment(undefined=StrictUndefined)
commit = "398879aba2a365049870709116a689618afeb5b7"
template_url = f"https://raw.githubusercontent.com/pawamoy/jinja-templates/{commit}/credits.md"
template_data = get_credits_data()
template_text = urllib.request.urlopen(template_url).read().decode(
"utf8") # noqa: S310
return jinja_env.from_string(template_text).render(**template_data)
with mkdocs_gen_files.open("credits.md", "w") as fd:
fd.write(get_credits())
mkdocs_gen_files.set_edit_path("credits.md", "gen_credits.py")
import os
import textwrap
import mkdocs_gen_files
root = mkdocs_gen_files.config["plugins"]["mkdocstrings"].get_handler(
"crystal").collector.root
nav = mkdocs_gen_files.open(f"api/index.md", "w")
for module in ["System", "Window", "Graphics", "Audio", "Network", ""]:
if module:
print(f"* [{module} module]({module.lower()}.md)", file=nav)
with mkdocs_gen_files.open(f"api/{module.lower()}.md", "w") as f:
f.write(
textwrap.dedent(f"""
# ::: SF
selection:
file_filters:
- '/{module.lower()}/'
"""))
for typ in root.lookup("SF").walk_types():
[cur_module] = {
os.path.dirname(os.path.relpath(loc.filename, "src"))
for loc in typ.locations
}
if module.lower() == cur_module:
name = typ.name
full_name = typ.abs_id
path = full_name.replace("::", "/")
for path in sorted(path_rustfst_module.rglob("*.py")): #
module_path = path.relative_to(path_rustfst_python).with_suffix("") #
doc_path = path.relative_to(path_rustfst_python).with_suffix(".md") #
full_doc_path = path_reference / doc_path #
parts = list(module_path.parts)
if parts[-1] == "__init__": #
parts = parts[:-1]
doc_path = doc_path.with_name("index.md")
full_doc_path = full_doc_path.with_name("index.md")
elif parts[-1] == "__main__":
continue
nav[parts] = doc_path.as_posix()
with mkdocs_gen_files.open(full_doc_path, "w") as fd: #
identifier = ".".join(parts) #
print("::: " + identifier, file=fd) #
mkdocs_gen_files.set_edit_path(full_doc_path, path)
with mkdocs_gen_files.open(path_reference / "SUMMARY.md", "w") as nav_file: #
nav_file.writelines(nav.build_literate_nav())
"""Generate the code reference pages and navigation."""
from pathlib import Path
import mkdocs_gen_files
nav = mkdocs_gen_files.Nav()
for path in sorted(Path("src").glob("**/*.py")):
module_path = path.relative_to("src").with_suffix("")
doc_path = path.relative_to("src", "aria2p").with_suffix(".md")
full_doc_path = Path("reference", doc_path)
parts = list(module_path.parts)
parts[-1] = f"{parts[-1]}.py"
nav[parts] = doc_path
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
ident = ".".join(module_path.parts)
print("::: " + ident, file=fd)
mkdocs_gen_files.set_edit_path(full_doc_path, path)
# add pages manually:
# nav["package", "module"] = "path/to/file.md"
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
nav_file.writelines(nav.build_literate_nav())
for module_type in kiara.module_mgmt.find_modules_for_package(
BASE_PACKAGE, include_pipelines=False
).keys():
if module_type == "pipeline":
continue
modules_page_content = modules_page_content + f"## ``{module_type}``\n\n"
modules_page_content = (
modules_page_content
+ "```\n{{ get_module_info('"
+ module_type
+ "') }}\n```\n\n"
)
with mkdocs_gen_files.open(modules_file_path, "w") as f:
f.write(modules_page_content)
pipelines_file_path = os.path.join("pipelines_list.md")
pipelines_page_content = """# Available pipeline module types
This page contains a list of all available *Kiara* pipeline module types, and their details.
!!! note
The formatting here will be improved later on, for now this should be enough to get the important details of each module type.
"""
for module_type in kiara.module_mgmt.find_modules_for_package(
BASE_PACKAGE, include_core_modules=False
):
def get_parts(typ):
parts = typ.abs_id.split("::")
assert parts[0] == "SunVox", parts
return parts[1:]
nav = mkdocs_gen_files.Nav()
nav_items = {}
for typ in [libsunvox] + list(libsunvox.walk_types()):
parts = typ.abs_id.split("::")
if parts[-1] == 'Attrs':
# Append to a pre-existing parent file
filename = '/'.join(parts[:-1]) + '.md'
with mkdocs_gen_files.open(filename, "a") as f:
print(f"## ::: {typ.abs_id}\n\n", file=f)
continue
filename = '/'.join(parts) + '.md'
with mkdocs_gen_files.open(filename, "w") as f:
print(f"# ::: {typ.abs_id}\n\n", file=f)
if typ.locations:
mkdocs_gen_files.set_edit_path(filename, typ.locations[0].url)
if len(parts) > 1:
typ2 = libsunvox.lookup(parts[1])
while (sup := typ2.superclass) and sup.abs_id.startswith("SunVox"):
parts = sup.abs_id.split("::") + parts[1:]
typ2 = sup.lookup()
import os.path
import mkdocs_gen_files
from echemdb.data import make_cvs_dataframe, collect_datapackages
from echemdb.make_pages import create_element_pages, create_element_surface_pages, create_systems_pages, render
data = make_cvs_dataframe(collect_datapackages())
create_systems_pages()
for elementname in list(set(data['electrode material'].values)):
create_element_pages(elementname)
for echemdb_id in list(set(data['echemdb-id'].values)):
with mkdocs_gen_files.open(
os.path.join("cv", "echemdb_pages", f"{echemdb_id}.md"),
'w') as out:
out.write(render("echemdb_id.md", echemdb_id=echemdb_id, cvs=data))
for tupled in data.groupby(by=['electrode material', 'surface']).groups:
create_element_surface_pages(tupled[0], tupled[1])
