finalizing the documentation

README.md

@@ -1,13 +1,71 @@
 [![Upload Python Package](https://github.com/JostTim/auto_fast_docs/actions/workflows/python-publish.yml/badge.svg?branch=main)](https://github.com/JostTim/auto_fast_docs/actions/workflows/python-publish.yml)
 [![Deploy](https://github.com/JostTim/auto_fast_docs/actions/workflows/ci-cd.yml/badge.svg?branch=main)](https://github.com/JostTim/auto_fast_docs/actions/workflows/ci-cd.yml)
 
-# Auto-Doc
-A single file auto documentation builder made to be interfaced with mkdocstrings, and ran in containerized CI/CD
+# Automatic documentation for your python repository. 
+With fast setup and no extra effort.
+This package is designed to be ran in containerized CI/CD.
+
+It's purpose is quite simple : 
+leveraging mkdocs, mkdocs-material and mkdocstrings, and scanning your repository's pyhton source files.  
+When it finds a function or class, it groups it nicely, and generates folders and markdown files with the appropriate mkdocstrings headers, inside a `docs` folder, used for the static website generation on github or gitlab pages.
+
+This folder will not appear in your repo if you run this package in a github/gitlab  CI/CD container, but will still exist at container runtime to generate and publish the website.
 
 ## Usage 
 
-Drop it on top level of your package wrapper folder.
-It requires a setup.py wrapped package structure like so :
+Drop it on top level of your package wrapper folder, and add two lines in your github/gitlab [ci/cd file](https://github.com/JostTim/auto_fast_docs/blob/main/.github/workflows/ci-cd.yml) : (click the link to see a working example, that built [this present repo's documentation page](https://josttim.github.io/auto_fast_docs/))
+
+```bash
+pip install auto_fast_docs
+auto_fast_docs MyPackage
+```
+
+**I strongly recommand giving it your username so that it can also build an mkdocs.yml file by itself !**
+
+```bash
+pip install auto_fast_docs
+auto_fast_docs MyPackage --username MyGtihubUsername
+```
+
+## Check the result
+
+[Here is an example of the result](https://josttim.github.io/auto_fast_docs/) (and also a documentation for this repo's code)
+
+## Install
+
+Pypi releases : https://pypi.org/project/auto-fast-docs/
+
+```bash
+pip install auto_fast_docs
+```
+
+or most recent commit from github :
+
+```bash
+pip install git+https://github.com/JostTim/auto_fast_docs.git
+```
+
+## Options :
+
+It supports a few options to simplify your dev life even more and be platform a-specific: 
+
+All options are case insensitive
+
+### --username
+Name of the user that owns the repository.
+If it is supplied and no ``mkdocs.yml`` file is present in the repo, auto_fast_doc will attempt to fill in the information automatically. If you don't supply this info, it will not generate the mkocs.yml file by itself.
+```bash
+auto_fast_docs MyPackage --username MyUsername 
+```
+
+### --layout
+Flat or src layout style of your code in the repository. By default, `layout="flat"`
+
+```bash
+auto_fast_docs MyPackage --layout src 
+```
+
+The flat layout structure is standardized like this :
 
 > - :open_file_folder: PackageRepo
 >   - :page_facing_up: setup.py
@@ -22,16 +80,52 @@ It requires a setup.py wrapped package structure like so :
 >       - :page_facing_up: \_\_init__.py
 >       - :page_facing_up: myfile2.py
     
-Then, inside the top wrapping folder, PackageRepo, you can call `auto-docs.py` like this :
+While the src layout is standardized like this :
+
+> - :open_file_folder: PackageRepo
+>   - :page_facing_up: setup.py
+>   - :page_facing_up: auto-doc.py
+>   - :page_facing_up: mkdocs.yml
+>   - :open_file_folder: docs
+>     - :page_facing_up: index.md
+>   - :open_file_folder: src
+>     - :open_file_folder: Package
+>       - :page_facing_up: \_\_init__.py
+>       - :page_facing_up: myfile.py
+>       - :open_file_folder: mysubpackage
+>         - :page_facing_up: \_\_init__.py
+>         - :page_facing_up: myfile2.py
+
+### --platform
+The platform (``github`` or ``gitlab``) on wich you are building the pages into.
+The default is ``github``
+
+```bash
+auto_fast_docs MyPackage --platform gitlab 
+```
+
+Note that in the case of gitlab, if you are not on the central gitlab.com repository but on a instance hosted by a compagny, you can supply the suffix after gitlab, separated with a semicolon ``:``
+
 ```bash
-python auto-docs.py Package
+auto_fast_docs MyPackage --platform gitlab:pasteur.fr
 ```
-It requires a single command line argument that tells it what is the folder that contains the python source files in your wrapping folder.   
 
-That's all !
+By default, if nothing is supplied with a semicolon after the platform name, the suffix is set to `com` (giving out github.com and gitlab.com)
+
+### --groups
+If your repository is not in your own package, you must supply the group name.(that's the organization name on github)
+
+```bash
+auto_fast_docs MyPackage --platform gitlab:pasteur.fr --groups mymaingroup/mysubgroup 
+```
+
+Note that if group is used, it is still necessary to supply the username - even thoug it is not used for the repository path assembly - if you want the ``mkdocs.yml`` file to be generated.
+
+In the case of gitlab, an arbitrary number of groups can be nested (while github doesn't allow nested organizations). Simmply separate them using forward slashes `/` and auto_fast_docs should manage to assemble the final path by itself, depending on your platform.
+
 _____
 
-**Small note :**  
+## Small note :
 On github, you will also need :
 - to allow Read and write permissions for workflow in your repo settings, under  
   ``settings > actions > general > Workflow permissions``
@@ -40,14 +134,3 @@ On github, you will also need :
   ``settings > pages > Build and deployment >  Branch`` to your `gh-pages` branch  
   (this branch will appear after the first sucessfull mkocs build, except if you created it yourself.)
 
-## Check the result
-
-[Here is an example of the result](https://josttim.github.io/auto_fast_docs/) (and also a documentation for this repo's code)
-
-## Install
-
-Install from Pypi : https://pypi.org/project/auto-fast-docs/
-
-```bash
-pip install auto_fast_docs
-```

auto_fast_docs/auto_doc.py

@@ -203,6 +203,7 @@ def run(self):
         LOGGER.info("Building with auto-doc :")
 
         # create and fill the .md files
+        self.create_index()
         nav_dic = self.make_markdown_files()
 
         doc_files_digest = ", \n - ".join(
@@ -280,11 +281,29 @@ def update_package_url(self):
     def update_doc_path(self):
         self.docpath = os.path.join(self.cwd, "docs")
         os.makedirs(self.docpath, exist_ok=True)
+
+    def create_index(self):
         index_file_path = os.path.join(self.docpath, "index.md")
-        if not os.path.isfile(index_file_path):
-            with open(index_file_path, "w") as f:
-                f.write(f"# {self.package_name}\n\n")
-                f.write(f"{self.package_name} source code documentation.\n")
+        if os.path.isfile(index_file_path):
+            return
+
+        content = ""
+
+        readme_file_paths = [os.path.join(self.cwd, suffix) for suffix in [
+            "README.md", "readme.md"]]
+        for readme_file_path in readme_file_paths:
+            if os.path.isfile(readme_file_path):
+                with open(readme_file_path, "r") as f:
+                    content = f.read()
+                LOGGER.info(
+                    f"created an index.md file from the {readme_file_path} file")
+                break
+
+        if content == "":
+            content = f"# {self.package_name}\n\n**{self.package_name}** codebase documentation.\n"
+
+        with open(index_file_path, "w") as f:
+            f.write(content)
 
     def update_static_doc_url(self):
         if self.username is None:
@@ -533,11 +552,6 @@ def current_content(self, with_nav=True) -> list:
                     help="Groups (on gitlab) or organisation (on hithub) on wich the repo is located. "
                     "Use / to separate groups if multiple are present (gitlab only)"
                     )
-parser.add_argument('-t',
-                    "--token",
-                    default="",
-                    help="github or gitlab token"
-                    )
 
 
 def console_mkds_make_docfiles():
@@ -557,8 +571,8 @@ def console_mkds_make_docfiles():
 
     if "github" in args.platform:
         command = "mkdocs gh-deploy --force"
-        if args.token:
-            command += f"--remote-name https://{args.token}@github.com/{args.username}/{args.package_name}.git"
+        # if args.token:
+        #     command += f"--remote-name https://{args.token}@github.com/{args.username}/{args.package_name}.git"
         subprocess.run(command, shell=True)
     elif "gitlab" in args.platform:
         command = "mkdocs build --site-dir public"