feat: ドキュメント周りを整備

doc_gen.py

@@ -0,0 +1,97 @@
+import os
+import importlib
+import inspect
+import subprocess
+import time
+from typing import TypedDict
+
+def get_defined_functions_and_classes(module):
+    functions = []
+    classes = []
+
+    for name, obj in inspect.getmembers(module):
+        if inspect.isfunction(obj) and obj.__module__ == module.__name__:
+            functions.append(name)
+        elif inspect.isclass(obj) and obj.__module__ == module.__name__:
+            classes.append(name)
+
+    return functions, classes
+
+
+class IGenerateSphinx(TypedDict):
+    module_path: str
+    module_name: str
+    functions: list[str]
+    classes: list[str]
+
+def generate_sphinx_output(data: list[IGenerateSphinx]):
+    output = []
+    output.append("API Reference\n===============\n")
+    tmp = {}
+    for i in hierarchy.values():
+        tmp[i] = []
+        #tmp[i].append(f"{i}\n{'-'*len(i)}")
+
+    tmp["__OTHER"] = []
+
+    def add_data(_data: IGenerateSphinx, add_to: list):
+        if _data['functions']:
+            for function in _data['functions']:
+                add_to.append(f"\n{function}\n" + "~" * len(function))
+                add_to.append(f".. autofunction:: {_data['module_name']}.{function}")
+
+        if _data['classes']:
+            for class_name in _data['classes']:
+                add_to.append(f"\n{class_name}\n" + "~" * len(class_name))
+                full_class_name = f"{_data['module_name']}.{class_name}"
+                add_to.append(f".. attributetable:: {full_class_name}")
+                add_to.append(f".. autoclass:: {full_class_name}\n    :members:")
+
+    for i in data:
+        add_to = "__OTHER"
+        for category in hierarchy.keys():
+            if category in  i['module_path']:
+                add_to = hierarchy[category]
+        add_data(i, tmp[add_to])
+
+    for k,v in tmp.items():
+        output.append(f"{k}\n{'-'*len(k)}")
+        output.append("\n\n".join(v))
+    return '\n'.join(output)
+
+
+def generate_documentation(base_path, output_file, hierarchy, exclude_files=[]):
+    documentation = []
+    items: list[IGenerateSphinx] = []
+
+    for file in [{'filename': file, 'root': root} for root, dirs, files in os.walk(base_path) if root != "__pycache__" for file in files]:
+        if file['filename'].endswith('.py') and file['filename'] not in exclude_files:
+
+            module_path = os.path.join(file['root'], file['filename'])
+            module_import_path = module_path.replace(os.path.sep, '.').replace('.py', '')
+
+            module = importlib.import_module(module_import_path)
+            functions, classes = get_defined_functions_and_classes(module)
+            if functions or classes:
+                items.append({"module_path":module_path, "module_name": module_import_path,"functions": functions,"classes": classes})
+    doc_content = generate_sphinx_output(items)
+    documentation.append(doc_content)
+    with open(output_file, 'w', encoding='utf-8') as doc_file:
+        doc_file.write('\n\n'.join(documentation))
+
+
+if __name__ == "__main__":
+    hierarchy = {
+        "mipac/models": "Misskey Models",
+        "mipac/manager": "Managers",
+        "mipac/actions": "Actions",
+        "mipac/types": "Type class",
+        "mipac/errors": "Errors"
+
+    }
+    source_path = "mipac"
+    output_path = "docs/index.rst"
+    excluded_files = ["__init__.py", "_version.py"]  # Add files to exclude here
+    generate_documentation(source_path, output_path, hierarchy, exclude_files=excluded_files)
+    os.chdir("./docs")
+    subprocess.run("sphinx-intl update -p _build/gettext && ./doc_builder.sh", shell=True)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,55 @@
+h1, h2, h3, h4, h5, h6 {
+    font-weight: normal;
+}
+
+h2 {
+    font-size: 1.7em;
+}
+
+h3 {
+    font-size: 1.5em;
+}
+
+.py-attribute-table {
+    display: flex;
+    flex-wrap: wrap;
+    background-color: var(--color-inline-code-background);
+    margin-bottom: -1rem;
+    border-radius: 4px 4px 0 0;
+    border-left: #5dcfff solid 2px;
+}
+
+.class > .sig-object {
+    background-color: var(--color-inline-code-background);
+    border-left: #5dcfff solid 2px;
+    border-radius: 0 0 0 3px;
+    margin-bottom: 2em;
+}
+
+dd > .deprecated {
+    border-left: solid goldenrod 7px;
+    border-top: solid goldenrod 7px;
+    border-radius: 5px;
+}
+
+.py-attribute-table-entry {
+    list-style: None;
+}
+
+.py-attribute-table-column {
+    flex: .5;
+}
+
+.py-attribute-table-column > span {
+    font-weight: bold;
+    margin-left: 1rem;
+}
+
+.py-attribute-table-badge {
+    font-weight: bold;
+    /* margin-right: .5rem; */
+}
+
+.sig {
+    background-color: var(--color-inline-code-background);
+}

docs/conf.py

@@ -0,0 +1,54 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('..'))
+sys.path.append(os.path.abspath('extensions'))
+
+project = 'mipac'
+copyright = '2023, yupix'
+author = 'yupix'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+
+    'attributetable'
+]
+
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+language = 'en'
+gettext_compact = False
+locale_dirs = ['locale/']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+
+html_theme = 'furo'
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
+
+html_theme_options = {
+    "sidebar_hide_name": True
+}
+
+# -- Options for todo extension ----------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
+
+todo_include_todos = True

docs/doc_builder.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+make html
+
+shopt -s dotglob
+
+support_language=('ja')
+for language in ${support_language[@]}
+do
+    make -e SPHINXOPTS="-D language='${language}'" -e BUILDDIR="./_build/html/${language}" html
+    cp -r ./_build/html/${language}/html/* ./_build/html/${language}/
+done