Repository files navigation

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 adocs 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.

Drop it on top level of your package wrapper folder, and add two lines in your github/gitlabci/cd file : (click the link to see a working example, that builtthis present repo's documentation page)

pip install auto_fast_docsauto_fast_docs MyPackage

I strongly recommand giving it your username so that it can also build an mkdocs.yml file by itself !

pip install auto_fast_docsauto_fast_docs MyPackage --username MyGtihubUsername

Here is an example of the result (and also a documentation for this repo's code)

Pypi releases :https://pypi.org/project/auto-fast-docs/

pip install auto_fast_docs

or most recent commit from github :

pip install git+https://github.com/JostTim/auto_fast_docs.git

It supports a few options to simplify your dev life even more and be platform a-specific:

All options are case insensitive, except for the positionnal argument package_name

Name of the user that owns the repository.If it is supplied and nomkdocs.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.

auto_fast_docs MyPackage --username MyUsername

Flat or src layout style of your code in the repository. By default,layout="flat"

auto_fast_docs MyPackage --layout src

The flat layout structure is standardized like this :

• 📂 PackageRepo
  • 📄 setup.py
  • 📄 pyproject.toml
  • 📄 mkdocs.yml
  • 📂 docs
    • 📄 index.md
  • 📂 Package
    • 📄 __init__.py
    • 📄 myfile.py
    • 📂 mysubpackage
      • 📄 __init__.py
      • 📄 myfile2.py

While the src layout is standardized like this :

• 📂 PackageRepo
  • 📄 setup.py
  • 📄 pyproject.toml
  • 📄 mkdocs.yml
  • 📂 docs
    • 📄 index.md
  • 📂 src
    • 📂 Package
      • 📄 __init__.py
      • 📄 myfile.py
      • 📂 mysubpackage
        • 📄 __init__.py
        • 📄 myfile2.py

Note that auto_fast_docs doesn't care aboutpyproject.toml orsetup.py, any can be used.Also note that the docs folder, and the mkdocs.yml file here are both also not necessary, if you supply at least the--username option (see above)
(and of course, if you are on github on a user hosted repo. Otherwise, see--platform and--groups options below)

The platform (github orgitlab) on wich you are building the pages into.The default isgithub

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:

auto_fast_docs MyPackage --platform gitlab:pasteur.fr

By default, if nothing is supplied with a semicolon after the platform name, the suffix is set tocom (giving out github.com and gitlab.com)

If your repository is not in your own package, you must supply the group name.(that's the organization name on github)

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 themkdocs.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.

On github, you will also need :

• to allow Read and write permissions for workflow in your repo settings, under
  settings > actions > general > Workflow permissions
• to set the pages deployments branch to gh-pages, under :
  settings > pages > Build and deployment > Source todeploy from a branch and
  settings > pages > Build and deployment > Branch to yourgh-pages branch
  (this branch will appear after the first sucessfull mkocs build, except if you created it yourself.)