EasyDocPy 1.2.0__tar.gz → 1.4.1__tar.gz

{easydocpy-1.2.0 → easydocpy-1.4.1}/EasyDocPy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EasyDocPy
-Version: 1.2.0
+Version: 1.4.1
 Summary: python documentation generator
 Author: epsilonkn
 License-Expression: MIT
@@ -19,6 +19,16 @@ The idea of that package is to create a technical documentation of a python sour
 
 For more information, read the wiki : https://github.com/epsilonkn/EasyDoc/wiki
 
+## Getting Started :
+
+**Using pip :**
+
+    pip install EasyDocPy
+
+**On github :**
+\
+Read the wiki of the module
+
 ## To use it : 
 
 ### To comment your code :
@@ -147,11 +157,11 @@ Explains a constant in the code. for now, all the constants are written at the b
     DEFAULT = "VOID"
 
 
-#### Generate the documentation :
+## Generate the documentation :
 
-### In a terminal :
+### For a file :
 
-Here is the only way implemented to generate a documentation in command line :
+To generate a documentation in command line :
 
     easydoc file "/your/path/to/file.py"
 
@@ -159,35 +169,57 @@ Note 1 : your terminal must be in the directory where you want to see the docume
 
 Note 2 : you can pass the path without double quotes, however it is better to keep them if your path got spaces in it.
 
-### In a python program :
 
-Disclaimer : Running the module in a program by calling directly the classes can be possible, but this might also opens a pandora box of bugs.
+### For a directory :
 
-The reason you would need to run the module manually in a python file is to get a better control over the process.
-Unfortunately, in the actual state of the module, the control over the module is still very little, this will be improved in the next updates.
+To generate a documentation in command line :
 
-If you still wish to do it in a program rather than in command line, here is the base :
+    easydoc dir "/your/path/to/dir"
 
-    From easydoc import Parser, MarkdownGenerator
+Note 1 : your terminal must be in the directory where you want to see the documentation generated.
+
+Note 2 : you can pass the path without double quotes, however it is better to keep them if your path got spaces in it.
 
-    parser = Parser(path = "/path/to/file.py", automatic = False)
-    parse_list = parser.get_parse()
-    file_header = parser.get_intro()
 
-    MarkdownGenerator(parse_list, file_header, doc_file_name)
+### Advanced generation :
 
+You can also choose to generate the documentation interactively :
 
+    easydoc interactive
 
-## Next updates :
+This way the package will ask you to enter the parameters, here they are :
 
-|Version | Improvement|
-|-|-|
-|V 1.2.0 | adding custom comment line to add info to the documentation|
-|V 1.3.0| better control over the process when done in a program |
-|V 1.4.0| adding doc generation for an entire directory |
-|V 1.5.0| adding user configuration |
-|......||
+__mandatory :__
 
-## API :
+- _type_ : type of document to treat : file | dir
+- _path_ : the path to what you want to treat (file or dir)
+
+__optional :__
+
+- _run_ : start the generation
+- _help_ : shows all the options and their usage
+- _exit_ : close the generation
+- _format_ | f : The format of the documentation | HTML implemented in (V1.5)
+- _language | lang_ : The language in which to doc is written | NOT IMPLEMENTED YET (V1.6 planned)
+- _recursive | rec_ : (dir only) : Enable/disable recursive file search in subdirs
+- _recursive_depth | rec_d_ : (dir only) Depth of recursive search, 0 equals to disable the recursive search
+- _onefile | of_ : (dir only) If enable, will generate the whole directory doc in a single file instead a doc file per source file 
+
+### Others arguements :
+
+__-v | --version :__ Shows the version of the package and stop the program.
+
+__--debug :__ Start the debug mode for generation, meaning package will print at each step what it's doing.
+
+
+## Next updates :
 
-For now there is no released API entry points in the module, you'll have to wait for the V1.3 and V1.5 for these parts
+|Version | Improvement| Status|
+|-|-|-|
+|V 1.2.0 | Adding custom comment line to add info to the documentation| Done |
+|V 1.3.0| Better control over the process when done in a program | suppressed from the planning |
+|V 1.4.0| V 4 : treatment of dirs \ V 1.4.1 : implementing main file usage in the process \ V 1.4.2 - implementing file meta data in onefile dir doc| In test...|
+|V 1.5.0| Generating the doc as a html file | |
+|V 1.6.0| Translation in differents languages | |
+|V 1.?.0| Adding user configuration | |
+|......|||

easydocpy-1.4.1/EasyDocPy.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+LICENSE
+README.md
+pyproject.toml
+EasyDocPy.egg-info/PKG-INFO
+EasyDocPy.egg-info/SOURCES.txt
+EasyDocPy.egg-info/dependency_links.txt
+EasyDocPy.egg-info/entry_points.txt
+EasyDocPy.egg-info/top_level.txt
+easydoc/__init__.py
+easydoc/__main__.py
+easydoc/classes/__init__.py
+easydoc/classes/exceptions.py
+easydoc/classes/parsed_objects.py
+easydoc/classes/tree_objects.py
+easydoc/config/custom_comment_lines.json
+easydoc/core/FileParser.py
+easydoc/core/InteractiveManager.py
+easydoc/core/TreatmentManager.py
+easydoc/core/__init__.py
+easydoc/core/utils/__init__.py
+easydoc/core/utils/const.py
+easydoc/core/utils/function_utils.py
+easydoc/generators/HTMLGenerator.py
+easydoc/generators/MarkdownGenerator.py
+easydoc/generators/__init__.py
+easydoc/templates/template.md

{easydocpy-1.2.0 → easydocpy-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EasyDocPy
-Version: 1.2.0
+Version: 1.4.1
 Summary: python documentation generator
 Author: epsilonkn
 License-Expression: MIT
@@ -19,6 +19,16 @@ The idea of that package is to create a technical documentation of a python sour
 
 For more information, read the wiki : https://github.com/epsilonkn/EasyDoc/wiki
 
+## Getting Started :
+
+**Using pip :**
+
+    pip install EasyDocPy
+
+**On github :**
+\
+Read the wiki of the module
+
 ## To use it : 
 
 ### To comment your code :
@@ -147,11 +157,11 @@ Explains a constant in the code. for now, all the constants are written at the b
     DEFAULT = "VOID"
 
 
-#### Generate the documentation :
+## Generate the documentation :
 
-### In a terminal :
+### For a file :
 
-Here is the only way implemented to generate a documentation in command line :
+To generate a documentation in command line :
 
     easydoc file "/your/path/to/file.py"
 
@@ -159,35 +169,57 @@ Note 1 : your terminal must be in the directory where you want to see the docume
 
 Note 2 : you can pass the path without double quotes, however it is better to keep them if your path got spaces in it.
 
-### In a python program :
 
-Disclaimer : Running the module in a program by calling directly the classes can be possible, but this might also opens a pandora box of bugs.
+### For a directory :
 
-The reason you would need to run the module manually in a python file is to get a better control over the process.
-Unfortunately, in the actual state of the module, the control over the module is still very little, this will be improved in the next updates.
+To generate a documentation in command line :
 
-If you still wish to do it in a program rather than in command line, here is the base :
+    easydoc dir "/your/path/to/dir"
 
-    From easydoc import Parser, MarkdownGenerator
+Note 1 : your terminal must be in the directory where you want to see the documentation generated.
+
+Note 2 : you can pass the path without double quotes, however it is better to keep them if your path got spaces in it.
 
-    parser = Parser(path = "/path/to/file.py", automatic = False)
-    parse_list = parser.get_parse()
-    file_header = parser.get_intro()
 
-    MarkdownGenerator(parse_list, file_header, doc_file_name)
+### Advanced generation :
 
+You can also choose to generate the documentation interactively :
 
+    easydoc interactive
 
-## Next updates :
+This way the package will ask you to enter the parameters, here they are :
 
-|Version | Improvement|
-|-|-|
-|V 1.2.0 | adding custom comment line to add info to the documentation|
-|V 1.3.0| better control over the process when done in a program |
-|V 1.4.0| adding doc generation for an entire directory |
-|V 1.5.0| adding user configuration |
-|......||
+__mandatory :__
 
-## API :
+- _type_ : type of document to treat : file | dir
+- _path_ : the path to what you want to treat (file or dir)
+
+__optional :__
+
+- _run_ : start the generation
+- _help_ : shows all the options and their usage
+- _exit_ : close the generation
+- _format_ | f : The format of the documentation | HTML implemented in (V1.5)
+- _language | lang_ : The language in which to doc is written | NOT IMPLEMENTED YET (V1.6 planned)
+- _recursive | rec_ : (dir only) : Enable/disable recursive file search in subdirs
+- _recursive_depth | rec_d_ : (dir only) Depth of recursive search, 0 equals to disable the recursive search
+- _onefile | of_ : (dir only) If enable, will generate the whole directory doc in a single file instead a doc file per source file 
+
+### Others arguements :
+
+__-v | --version :__ Shows the version of the package and stop the program.
+
+__--debug :__ Start the debug mode for generation, meaning package will print at each step what it's doing.
+
+
+## Next updates :
 
-For now there is no released API entry points in the module, you'll have to wait for the V1.3 and V1.5 for these parts
+|Version | Improvement| Status|
+|-|-|-|
+|V 1.2.0 | Adding custom comment line to add info to the documentation| Done |
+|V 1.3.0| Better control over the process when done in a program | suppressed from the planning |
+|V 1.4.0| V 4 : treatment of dirs \ V 1.4.1 : implementing main file usage in the process \ V 1.4.2 - implementing file meta data in onefile dir doc| In test...|
+|V 1.5.0| Generating the doc as a html file | |
+|V 1.6.0| Translation in differents languages | |
+|V 1.?.0| Adding user configuration | |
+|......|||

{easydocpy-1.2.0 → easydocpy-1.4.1}/README.md

@@ -6,6 +6,16 @@ The idea of that package is to create a technical documentation of a python sour
 
 For more information, read the wiki : https://github.com/epsilonkn/EasyDoc/wiki
 
+## Getting Started :
+
+**Using pip :**
+
+    pip install EasyDocPy
+
+**On github :**
+\
+Read the wiki of the module
+
 ## To use it : 
 
 ### To comment your code :
@@ -134,11 +144,11 @@ Explains a constant in the code. for now, all the constants are written at the b
     DEFAULT = "VOID"
 
 
-#### Generate the documentation :
+## Generate the documentation :
 
-### In a terminal :
+### For a file :
 
-Here is the only way implemented to generate a documentation in command line :
+To generate a documentation in command line :
 
     easydoc file "/your/path/to/file.py"
 
@@ -146,35 +156,57 @@ Note 1 : your terminal must be in the directory where you want to see the docume
 
 Note 2 : you can pass the path without double quotes, however it is better to keep them if your path got spaces in it.
 
-### In a python program :
 
-Disclaimer : Running the module in a program by calling directly the classes can be possible, but this might also opens a pandora box of bugs.
+### For a directory :
 
-The reason you would need to run the module manually in a python file is to get a better control over the process.
-Unfortunately, in the actual state of the module, the control over the module is still very little, this will be improved in the next updates.
+To generate a documentation in command line :
 
-If you still wish to do it in a program rather than in command line, here is the base :
+    easydoc dir "/your/path/to/dir"
 
-    From easydoc import Parser, MarkdownGenerator
+Note 1 : your terminal must be in the directory where you want to see the documentation generated.
+
+Note 2 : you can pass the path without double quotes, however it is better to keep them if your path got spaces in it.
 
-    parser = Parser(path = "/path/to/file.py", automatic = False)
-    parse_list = parser.get_parse()
-    file_header = parser.get_intro()
 
-    MarkdownGenerator(parse_list, file_header, doc_file_name)
+### Advanced generation :
 
+You can also choose to generate the documentation interactively :
 
+    easydoc interactive
 
-## Next updates :
+This way the package will ask you to enter the parameters, here they are :
 
-|Version | Improvement|
-|-|-|
-|V 1.2.0 | adding custom comment line to add info to the documentation|
-|V 1.3.0| better control over the process when done in a program |
-|V 1.4.0| adding doc generation for an entire directory |
-|V 1.5.0| adding user configuration |
-|......||
+__mandatory :__
 
-## API :
+- _type_ : type of document to treat : file | dir
+- _path_ : the path to what you want to treat (file or dir)
+
+__optional :__
+
+- _run_ : start the generation
+- _help_ : shows all the options and their usage
+- _exit_ : close the generation
+- _format_ | f : The format of the documentation | HTML implemented in (V1.5)
+- _language | lang_ : The language in which to doc is written | NOT IMPLEMENTED YET (V1.6 planned)
+- _recursive | rec_ : (dir only) : Enable/disable recursive file search in subdirs
+- _recursive_depth | rec_d_ : (dir only) Depth of recursive search, 0 equals to disable the recursive search
+- _onefile | of_ : (dir only) If enable, will generate the whole directory doc in a single file instead a doc file per source file 
+
+### Others arguements :
+
+__-v | --version :__ Shows the version of the package and stop the program.
+
+__--debug :__ Start the debug mode for generation, meaning package will print at each step what it's doing.
+
+
+## Next updates :
 
-For now there is no released API entry points in the module, you'll have to wait for the V1.3 and V1.5 for these parts
+|Version | Improvement| Status|
+|-|-|-|
+|V 1.2.0 | Adding custom comment line to add info to the documentation| Done |
+|V 1.3.0| Better control over the process when done in a program | suppressed from the planning |
+|V 1.4.0| V 4 : treatment of dirs \ V 1.4.1 : implementing main file usage in the process \ V 1.4.2 - implementing file meta data in onefile dir doc| In test...|
+|V 1.5.0| Generating the doc as a html file | |
+|V 1.6.0| Translation in differents languages | |
+|V 1.?.0| Adding user configuration | |
+|......|||

easydocpy-1.4.1/easydoc/__init__.py

@@ -0,0 +1,6 @@
+#/actual_version : 1.4.0
+#/file_intro
+"""
+This package is the root of EasyDoc and exports the package-level modules
+used by the CLI and by a Python import.
+"""

easydocpy-1.4.1/easydoc/__main__.py

@@ -0,0 +1,59 @@
+#/actual_version : 1.2.8
+#/TODO Add language option support and improved CLI validation
+#/file_intro
+"""
+This script is the CLI entry point for EasyDoc. It parses CLI options,
+validates the requested path, and starts file or directory documentation generation.
+"""
+
+from argparse import ArgumentParser
+from importlib.metadata import version
+
+from easydoc.core import (
+    TreatmentManager, 
+    InteractiveManager, 
+    is_valid_path, 
+    TYPES, 
+    FORMATS, 
+    LANGUAGES
+)
+
+parser = ArgumentParser()
+parser.add_argument("-v", "--version", 
+                    action="store_true", 
+                    help="show the version of EasyDocPy and exit")
+parser.add_argument("type",
+                    nargs="?",
+                    choices= TYPES + ["interactive"], 
+                    help="the type of document to treat, either a single file or a whole directory, interactive mode allows to set the arguments interactively")
+parser.add_argument("path", 
+                    nargs="?",
+                    help="the path to the file or directory to document")
+parser.add_argument("-f", "--format", 
+                    choices=FORMATS,
+                    help="the format of the documentation to generate")
+parser.add_argument("-l", "--language", 
+                    choices=LANGUAGES,
+                    help="the language of the documentation to generate")
+parser.add_argument("--debug", 
+                    default=False,
+                    action="store_true",
+                    help="enable debug mode")
+args = parser.parse_args()
+
+if args.version:
+    print("EasyDocPy", version("EasyDocPy"))
+    exit(0)
+
+
+
+match args.type :
+    case "file" | "dir":
+        if not is_valid_path(args.path): 
+            raise ValueError(f"Invalid path: The path {args.path} doesn't point to a python file")
+        TreatmentManager(path = args.path, type = args.type, format = args.format, debug = args.debug)
+    case "interactive":
+        modif_args = InteractiveManager.run()
+        TreatmentManager(**modif_args, debug=args.debug)
+    case _ :
+        raise ValueError(f"Invalid value for type : {args.type}. The type of document to treat must be  [{', '.join(TYPES)}] or 'interactive'")

easydocpy-1.4.1/easydoc/classes/__init__.py

@@ -0,0 +1,20 @@
+#/actual_version : 1.0.0
+#/file_intro
+"""
+This package initializer exposes the parsed object and tree classes
+needed by the EasyDoc core modules.
+"""
+
+from .parsed_objects import *
+from .exceptions import *
+from .tree_objects import Node, Leaf
+
+__all__ = [
+"Parsed_file",
+"Parsed_class", 
+"Parsed_function", 
+"Custom_comment",
+"NotDeveloppedError",
+"Node",
+"Leaf"
+]

easydocpy-1.4.1/easydoc/classes/exceptions.py

@@ -0,0 +1,11 @@
+#/file_intro
+"""
+Exception classes for EasyDoc.
+
+This module defines custom exception types used by the EasyDoc package.
+"""
+
+
+class NotDeveloppedError(Exception):
+    """Raised when a feature is not yet implemented."""
+    pass

easydocpy-1.4.1/easydoc/classes/parsed_objects.py

@@ -0,0 +1,136 @@
+#/actual_version : 1.2.0
+#/TODO Update parsed object for decorators and nested classes
+#/TODO Take in count the return type of the functions
+#/file_intro
+"""
+This module declares the parsed object containers that represent file structure,
+function and class metadata, and extracted custom comments.
+"""
+
+import re
+from typing import Union
+
+
+class Parsed_object:
+
+    def __init__(self, name : str, level : int = 0):
+        """Initialize a parsed object.
+
+        Args:
+            name (str): The file name or file path.
+            content_list (list[Parsed_class, Parsed_function]): Parsed classes and functions.
+            file_data (list[Custom_comment]): Custom comments extracted from the file.
+        """
+        self.name = name
+        self.content : list["Parsed_object"] = []
+        self.comments : list["Custom_comment"] = []
+        self.level = level
+        self.docstring : str = ""
+
+
+    def add_content(self, content : Union["Parsed_object"]):
+        self.content.append(content)
+
+
+    def add_comment(self, data : "Custom_comment"):
+        self.comments.append(data)
+
+
+
+class Parsed_file(Parsed_object):
+    """Represents a parsed Python file and its content."""
+
+    def __init__(self, name : str):
+        """Initialize a parsed file container.
+
+        Args:
+            name (str): The file name or file path.
+            content_list (list[Parsed_class, Parsed_function]): Parsed classes and functions.
+            file_data (list[Custom_comment]): Custom comments extracted from the file.
+        """
+        super().__init__(name, 0)
+        self.name = name
+
+
+class Parsed_function(Parsed_object):
+    """Represents a parsed function """
+
+    def __init__(self, declaration : str, type_ : str, level : int = 1):
+        """Initialize a parsed function.
+
+        Args:
+            declaration (str): The declaration line or block containing the def.
+            docstring (str): The docstring content associated with the declaration.
+        """
+        super().__init__("", level)
+        self.declaration : str = ""
+        self.set_declaration(declaration)
+        self.funct_type = type_
+
+
+    def set_declaration(self, declaration):
+        """Extract the function name from the declaration.
+
+        Args:
+            declaration (str): The function declaration string.
+        """
+        self.declaration = declaration
+        self.name = re.search(r"^\s*def\s+([a-zA-Z_]\w*)", declaration).group(1)
+
+    
+    def __str__(self):
+        """Return the parsed element name."""
+        return self.name
+
+
+
+class Custom_comment:
+    """Represents a custom comment block extracted from source files."""
+
+    def __init__(self, type_ : str, ref : str , title : str, is_list : bool, content : str):
+        """Initialize a custom comment block.
+
+        Args:
+            type_ (str): The type of custom comment.
+            ref (str): The reference token used to replace custom comment placeholders.
+            title (str): The title of the custom comment.
+            is_list (bool): Whether the comment should be treated as a list.
+            content (str): The comment content.
+        """
+        self.type_ : str = type_
+        self.title : str = title
+        self.ref : str = ref
+        self.is_list : bool = is_list
+        self.content : str = content
+
+
+
+class Parsed_class(Parsed_object):
+    """Represents a parsed class and its methods."""
+
+    def __init__(self, declaration, level : int = 1):
+        """Initialize a parsed class.
+
+        Args:
+            declaration (str): The class declaration string.
+            docstring (str): The class docstring content.
+        """
+        super().__init__("", level)
+        self.declaration : str = ""
+        self.set_declaration(declaration)
+        self.level = level
+
+
+    def set_declaration(self, declaration):
+        """Extract the class name from the declaration.
+
+        Args:
+            declaration (str): The class declaration string.
+        """
+        self.declaration = declaration
+        self.name = re.search(r"^\s*class\s+([a-zA-Z_]\w*)", declaration).group(1)
+
+
+    def __str__(self):
+        """Return the class name."""
+        return self.name