131 lines
4.3 KiB
Python
131 lines
4.3 KiB
Python
# pyChaChaDummyProject (c) by chacha
|
|
#
|
|
# pyChaChaDummyProject is licensed under a
|
|
# Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Unported License.
|
|
#
|
|
# You should have received a copy of the license along with this
|
|
# work. If not, see <https://creativecommons.org/licenses/by-nc-sa/4.0/>.
|
|
|
|
from __future__ import annotations
|
|
from typing import TYPE_CHECKING
|
|
|
|
import shutil
|
|
import os
|
|
import sys
|
|
import subprocess
|
|
from pathlib import Path
|
|
from distutils.dir_util import copy_tree
|
|
|
|
import yaml
|
|
|
|
try:
|
|
from yaml import CLoader as Loader, CDumper as Dumper
|
|
except ImportError:
|
|
from yaml import Loader, Dumper
|
|
|
|
from .helper_base import helper_withresults_base
|
|
|
|
|
|
class doc_gen(helper_withresults_base):
|
|
enable_gen_pdf: bool = False
|
|
|
|
@classmethod
|
|
def do_job(cls):
|
|
print(cls.project_rootdir_path)
|
|
print()
|
|
|
|
# create doc root dir
|
|
doc_path = cls.project_rootdir_path / "docs"
|
|
cls._reset_dir(doc_path)
|
|
|
|
site_path = cls.get_result_dir() / "site"
|
|
cls._reset_dir(site_path)
|
|
|
|
# copy files from main project dir
|
|
shutil.copyfile(
|
|
str(cls.project_rootdir_path / "README.md"), str(doc_path / "README.md")
|
|
)
|
|
shutil.copyfile(
|
|
str(cls.project_rootdir_path / "LICENSE.md"), str(doc_path / "LICENSE.md")
|
|
)
|
|
|
|
# copy files from static-doc dir
|
|
copy_tree(str(cls.project_rootdir_path / "docs-static"), str(doc_path))
|
|
|
|
# generating API doc + nav from python docstrings
|
|
reference_path = doc_path / "reference"
|
|
cls._reset_dir(reference_path)
|
|
|
|
for path in sorted((cls.project_rootdir_path / "src").rglob("*.py")):
|
|
module_path = path.relative_to(
|
|
cls.project_rootdir_path / "src"
|
|
).with_suffix("")
|
|
doc_path = path.relative_to(cls.project_rootdir_path / "src").with_suffix(
|
|
".md"
|
|
)
|
|
full_doc_path = Path(reference_path, doc_path)
|
|
|
|
parts = list(module_path.parts)
|
|
|
|
if parts[-1] == "__init__":
|
|
parts = parts[:-1]
|
|
elif parts[-1] == "__main__":
|
|
continue
|
|
|
|
cls._reset_dir(os.path.dirname(full_doc_path))
|
|
with open(full_doc_path, "w+") as fd:
|
|
identifier = "src." + ".".join(parts)
|
|
print("::: " + identifier, file=fd)
|
|
|
|
cmdopts = [
|
|
f"{sys.executable}",
|
|
"-m",
|
|
"mkdocs",
|
|
"-v",
|
|
"build",
|
|
"--site-dir",
|
|
str(site_path),
|
|
"--clean",
|
|
]
|
|
|
|
# little hack here, to enable / disable pdf generation using own class config
|
|
# => reason is mkdocs seems to try loading the plugin even if we disable it, so we need to
|
|
# manually process the configuration file.
|
|
mkdocsCfg = None
|
|
with open(cls.project_rootdir_path / "mkdocs.yml", "r") as mkdocsCfgFile:
|
|
mkdocsCfg = yaml.load(mkdocsCfgFile, Loader=yaml.SafeLoader)
|
|
|
|
if cls.enable_gen_pdf == True:
|
|
mkdocsCfg["plugins"].append(
|
|
{
|
|
"with-pdf": {
|
|
"cover_subtitle": "User Manual",
|
|
"cover_logo": str(
|
|
cls.project_rootdir_path / "docs-static" / "Library.jpg"
|
|
),
|
|
"verbose": False,
|
|
"media_type": "print",
|
|
"headless_chrome_path": "chromium",
|
|
"exclude_pages": ["LICENSE"],
|
|
"output_path": str(site_path / "pdf" / "manual.pdf"),
|
|
}
|
|
}
|
|
)
|
|
else:
|
|
for subelem in mkdocsCfg["plugins"]:
|
|
if isinstance(subelem, dict):
|
|
if "with-pdf" in subelem.keys():
|
|
mkdocsCfg["plugins"].remove(subelem)
|
|
break
|
|
|
|
with open(cls.project_rootdir_path / "mkdocs.yml", "w") as mkdocsCfgFile:
|
|
mkdocsCfgFile.write(
|
|
yaml.dump(
|
|
mkdocsCfg, Dumper=Dumper, default_flow_style=False, sort_keys=False
|
|
)
|
|
)
|
|
|
|
res = cls.run_cmd(cmdopts)
|
|
print(res.decode())
|
|
print(" !! done")
|