improve doc generation

make a run configuration for doc
2023-03-25 14:40:26 +00:00
parent 8cafaa5ccb
commit de26b3ffb8
7 changed files with 154 additions and 110 deletions
--- a/README.md
+++ b/README.md
@@ -13,6 +13,4 @@
 A simple changelog formater that consume raw changes list text and produce nice pre-formated changelogs.
 The input data mainly aim to be a merged commit report.

-Checkout [Latest Documentation](https://chacha.ddns.net/mkdocs-web/chacha/pychangelogfactory/master/latest/).
-
-## Features
+Checkout [Latest Documentation](https://chacha.ddns.net/mkdocs-web/chacha/pychangelogfactory/master/latest/).
--- a/docs-static/usage.md
+++ b/docs-static/usage.md
@@ -8,8 +8,8 @@ _It's up to the user to provide this merged history._

 To realize this job, parsing is done in two rounds:

- first round extrats formal changes messages: e.g.: <change_type>(<change_target>): <change_message>
- secound round extracts lines from remaining ones based on keywords dictionnaries
+- first round extrats formal changes messages: e.g.: `<change_type>(<change_target>): <change_message>`
+- secound round extracts lines from remaining ones, based on keywords dictionnaries

 /// warning | searching policy
 When formal search (1), _lines must contain at least 2 words_
@@ -41,8 +41,8 @@ From master git repository:
 ## Use in your project

 ### Sample code
-```python
-#from pychangelogfactory import ChangeLogFormater
+``` py
+from pychangelogfactory import ChangeLogFormater

 raw_changelog='''
 feat: add a nice feature to the project
@@ -60,10 +60,8 @@ print(changelog)
    #### Security :shield::
    > security: fix a security leak on the Foo2 component
    
-### Output
-/// define
+### Output (rendered)
 #### Features      :sparkles::
 > feat: add a nice feature to the project
 #### Security :shield::
 > security: fix a security leak on the Foo2 component
-///
--- a/helpers/doc_gen.py
+++ b/helpers/doc_gen.py
@@ -72,9 +72,11 @@ class doc_gen(helper_withresults_base):
        # 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)
+            mkdocsCfg = yaml.load(mkdocsCfgFile, Loader=yaml.Loader)
+
+            if "plugins" in mkdocsCfg:
+                mkdocsCfg["plugins"] = [_ for _ in mkdocsCfg["plugins"] if (not isinstance(_, dict) or "with-pdf" not in _.keys())]

            if cls.enable_gen_pdf == True:
                mkdocsCfg["plugins"].append(
@@ -83,19 +85,11 @@ class doc_gen(helper_withresults_base):
                            "cover_subtitle": "User Manual",
                            "cover_logo": str(cls.project_rootdir_path / "docs-static" / "Library.jpg"),
                            "verbose": False,
-                            "media_type": "print",
                            "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))

--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,15 +1,8 @@
-# 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/>.
-
 docs_dir: docs
 site_name: pychangelogfactory
 site_url: https://chacha.ddns.net/mkdocs-web/chacha/pychangelogfactory/latest/
-site_description: A simple changelog builder that you can feed with your repository change history
+site_description: A simple changelog builder that you can feed with your repository
+  change history
 site_author: chacha
 repo_url: https://chacha.ddns.net/gitea/chacha/pychangelogfactory
 use_directory_urls: false
@@ -17,81 +10,109 @@ copyright: CC BY-NC-SA 4.0
 theme:
  name: material
  features:
-    - navigation.instant
-    - navigation.tracking
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - toc.integrate
-    - navigation.top
+  - navigation.instant
+  - navigation.tracking
+  - navigation.tabs
+  - navigation.tabs.sticky
+  - navigation.footer
+  - toc.integrate
+  - navigation.top
+  - navigation.section
+  - content.code.annotate
+  - navigation.prune
+  - toc.follow
  palette:
-    - media: '(prefers-color-scheme: dark)'
-      scheme: slate
-      toggle:
-        icon: material/brightness-4
-        name: Switch to system preference
-    - media: (prefers-color-scheme)
-      toggle:
-        icon: material/brightness-auto
-        name: Switch to light mode
-    - media: '(prefers-color-scheme: light)'
-      scheme: default
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
+  - media: '(prefers-color-scheme: dark)'
+    scheme: slate
+    toggle:
+      icon: material/brightness-4
+      name: Switch to system preference
+  - media: (prefers-color-scheme)
+    toggle:
+      icon: material/brightness-auto
+      name: Switch to light mode
+  - media: '(prefers-color-scheme: light)'
+    scheme: default
+    toggle:
+      icon: material/brightness-7
+      name: Switch to dark mode
 plugins:
-  - search
-  - markdownextradata
-  - mermaid2
-  - localsearch
-  - autorefs
-  - mkdocstrings:
-      default_handler: python
-      handlers:
-        python:
-          selection:
-            filters:
-              - '!^_(?!_init__)'
-            inherited_members: true
-          rendering:
-            show_root_heading: false
-            show_root_toc_entry: false
-            show_root_full_path: false
-            show_if_no_docstring: true
-            show_signature_annotations: true
-            show_source: false
-            heading_level: 2
-            group_by_category: true
-            show_category_heading: true
+- search
+- markdownextradata
+- mermaid2
+- localsearch
+- mkdocstrings:
+    default_handler: python
+    handlers:
+      python:
+        options:
+          filters:
+          - '!^_[^_]'
+          inherited_members: true
+          show_if_no_docstring: true
+          show_signature_annotations: true
+          show_source: false
+          show_category_heading: true
+          group_by_category: true
+          docstring_section_style: spacy
+          show_root_full_path: false
+          merge_init_into_class: true
+          separate_signature: true
+- with-pdf:
+    cover_subtitle: User Manual
+    cover_logo: C:\Users\chacha\git\pychangelogfactory\docs-static\Library.jpg
+    verbose: false
+    exclude_pages:
+    - LICENSE
+    output_path: C:\Users\chacha\git\pychangelogfactory\helpers-results\doc_gen\site\pdf\manual.pdf
 markdown_extensions:
-  - def_list
-  - tables
-  - attr_list
-  - abbr
-  - pymdownx.blocks.admonition
-  - pymdownx.blocks.define
-  - pymdownx.blocks.details
-  - pymdownx.blocks.tab
-  - pymdownx.blocks.html
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.critic
-  - pymdownx.details
-  - pymdownx.inlinehilite
-  - pymdownx.snippets
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.keys
-  - pymdownx.mark
-  - pymdownx.progressbar
-  - pymdownx.smartsymbols
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
-  - footnotes
-
+- def_list
+- tables
+- attr_list
+- abbr
+- pymdownx.blocks.admonition:
+    types:
+    - new
+    - settings
+    - note
+    - abstract
+    - info
+    - tip
+    - success
+    - question
+    - warning
+    - failure
+    - danger
+    - bug
+    - example
+    - quote
+- pymdownx.blocks.definition
+- pymdownx.blocks.details
+- pymdownx.blocks.tab
+- pymdownx.blocks.html
+- pymdownx.betterem:
+    smart_enable: all
+- pymdownx.caret
+- pymdownx.critic
+- pymdownx.details
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- pymdownx.highlight:
+    anchor_linenums: true
+    line_spans: __span
+    pygments_lang_class: true
+- pymdownx.keys
+- pymdownx.mark
+- pymdownx.progressbar
+- pymdownx.smartsymbols
+- pymdownx.tasklist:
+    custom_checkbox: true
+- pymdownx.tilde
+- footnotes
+- pymdownx.superfences
+- pymdownx.emoji:
+    emoji_index: !!python/name:materialx.emoji.twemoji
+    emoji_generator: !!python/name:materialx.emoji.to_svg
 extra:
  branch: master
-  repository: pygitversionhelper
+  repository: pygitversionhelper
--- a/pychangelogfactory_mkdocs.launch
+++ b/pychangelogfactory_mkdocs.launch
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<launchConfiguration type="org.python.pydev.debug.regularLaunchConfigurationType">
+    <booleanAttribute key="org.eclipse.debug.core.ATTR_FORCE_SYSTEM_CONSOLE_ENCODING" value="false"/>
+    <listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_PATHS">
+        <listEntry value="/pychangelogfactory/helpers"/>
+    </listAttribute>
+    <listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_TYPES">
+        <listEntry value="2"/>
+    </listAttribute>
+    <mapAttribute key="org.eclipse.debug.core.environmentVariables">
+        <mapEntry key="PATH" value="C:\Program Files\GTK3-Runtime Win64\bin"/>
+    </mapAttribute>
+    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:pychangelogfactory/helpers}"/>
+    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_OTHER_WORKING_DIRECTORY" value=""/>
+    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_TOOL_ARGUMENTS" value="--doc-gen --doc-gen-pdf"/>
+    <stringAttribute key="org.python.pydev.debug.ATTR_INTERPRETER" value="__default"/>
+    <stringAttribute key="org.python.pydev.debug.ATTR_PROJECT" value="pychangelogfactory"/>
+    <stringAttribute key="process_factory_id" value="org.python.pydev.debug.processfactory.PyProcessFactory"/>
+</launchConfiguration>
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -59,7 +59,7 @@ coverage-check    = ["coverage>=7.0"]
 complexity-check  = ["radon>=5.1"]
 quality-check     = ["pylint>=2.15","pylint-json2html>=0.4","pandas>=1.5"]
 type-check        = ["mypy[reports]>=0.99" ]
-doc-gen           = ["mkdocs>=1.4.0", "mkdocs-material>=8.5", "mkdocs-localsearch>=0.9.0", "mkdocstrings[python]>=0.19", "mkdocs-with-pdf>=0.9.3","pyyaml>=6.0","pymdown-extensions>=9","mkdocs-markdownextradata-plugin","mkdocs-mermaid2-plugin"]
+doc-gen           = ["mkdocs>=1.4.0", "mkdocs-material>=8.5","mkdocs-pymdownx-material-extras", "mkdocs-localsearch>=0.9.0", "mkdocstrings[python]>=0.19", "mkdocs-with-pdf>=0.9.3","pyyaml>=6.0","pymdown-extensions>=9","mkdocs-markdownextradata-plugin","mkdocs-mermaid2-plugin"]

 #[project.scripts]
 #my-script = "my_package.module:function"
--- a/src/pychangelogfactory/changelogfactory.py
+++ b/src/pychangelogfactory/changelogfactory.py
@@ -9,7 +9,7 @@
 # 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/>.

-"""#A simple changelog formater that consume merged commit message and produce nice pre-formated changelogs.
+"""A simple changelog formater that consume merged commit message and produce nice pre-formated changelogs.

 """

@@ -31,8 +31,11 @@ def ChangeLogFormaterRecordType(Klass: type) -> type:

 class ChangeLogFormater(ABC):
    """The main changelog class that define nearly everythings.
-    this was supposed to be a very shorty script this is why it is all-in-one...
-    factory and base-object are mixed.
+
+    This was supposed to be a very shorty script this is why it is all-in-one...
+    /// warning
+    Factory and base-objects are mixed in the same class.
+    ///
    """

    ar_Klass: list[ChangeLogFormater] = []
@@ -44,6 +47,17 @@ class ChangeLogFormater(ABC):
    priority: int = 0

    def __init__(self, scope: str | None, ChangelogString: str):
+        """Main ChangeLogFormater class constructor
+
+        This class contain both formater and factory.
+
+        /// warning
+        this class does not aim to be instantiated by user.
+        ///
+        Args:
+            scope: scope of the formater (tag)
+            ChangelogString: formater rendered title
+        """
        self._scope = scope
        self._ChangelogString = ChangelogString.strip()

@@ -264,9 +278,9 @@ for RecordType, Config in {
    # fmt: on
 }.items():
    # then we instantiate all of them
-    name = f"ChangeLogFormater_{RecordType}"
-    tmp = globals()[name] = type(
-        name,
+    _name = f"ChangeLogFormater_{RecordType}"
+    _tmp = globals()[_name] = type(
+        _name,
        (ChangeLogFormater,),
        {
            "prefix": RecordType,
@@ -275,7 +289,7 @@ for RecordType, Config in {
            "priority": Config[0],
        },
    )
-    ChangeLogFormater.ar_Klass.append(tmp)
+    ChangeLogFormater.ar_Klass.append(_tmp)


@ChangeLogFormaterRecordType