Package: pymkdocs
pyMkDocs UtilityWhat is pyMkDocs?pyMkDocs is a tool to generate documentation for Python projects.
It extends the features ofMkDocs.
It is, itself written inPython.Why was this project created?MkDocsis an amazing tool to generate a website with
Markdown. Until now, however, there
was no tool forauto generatinga MkDocs project from Python source.The typical starting point when comparing Python documentation generators, is
the standard library'spydocmodule.
While that tool is easy to use, it's not flexible, and the end result leaves
something to be desired. In contrast, many would consider the "gold standard" for
auto generating Python documentation to beSphinx.
But that tool is complicated, and usesreStructuredText.
Too bad reStructuredTextsucks,Markdownrocks!As the real work involved in documenting your code will end up revolving
around writingDoc Stringsone way
or another, being able to express yourself in that context via Markdown will make
you HAPPY for a long time to come!How do I install it?pip install pymkdocsRecipe to make it work:Ingredients:1 folder containing Python source files (e.g. theexamplefolder in this repo)OR1 freshpip install(OPTIONAL) custom Docstrings and/or "magic comments" included in source (see below)Easy steps:Install pyMkDocs.Open a terminal and change to the project directory. Example:cd pymkdocsRun pyMkDocs. Example:pymkdocs example/src example -r -c -sCommand line help:| pyMkDocs |
This utility generates MkDocs websites from Python source code.
Help:  pymkdocs -h/--help
Usage: pymkdocs source destination [-m/-r] [-c] [-s]
-m: magic mode (default) / -r: raw mode
-c: include source code
-s: serve test siteHow does this work?pyMkDocs analyzes your Python source and generates markdown files from them.
It then employs MkDocs to produce html based documentation from the markdown!
This process creates:a 'mkdocs.yml' file, which is a config file forMkDocsa 'docs' folder, containing the markdowna 'site' folder, which is the final web site producedRaw ModeThe easiest way to learn to use pyMkDocs may be to first run the example
provided in "Raw Mode". Pass the-rswitch on the command line to enable
this option. Using this method for generating the documentation, the entire
directory tree for a source path specified is recursively scanned and all
elements of the code indexed. The files produced have a direct one-to-one
alignment of Python package / module to a sub directory / document
(i.e. site page).This is the most straightforward style for indexing the exact source
found within that Python code base in a literal manner.Magic ModeNow that you've seen how easy it is to use "Raw Mode", let's dive into "Magic Mode"!"Magic Mode" is used to generate documentation sites in a more dynamic,
customizable manner. The key difference between this mode vs. "Raw Mode", is that
the method by which objects are indexed is "by import" rather than by "file path".
This mode also provides the means to define the structure of the content produced
to a notable degree.The way objects are found in this mode aligns with how the content of a package
naturally resolves via import within a Python runtime context. The source elements
which are explicitly included within a given Python package's__init__module
will be indexed by the doc generator's parser / inspector.The command line argument passed for the "source" argument may simply be the
name of an import. That argument does not have to be the path to its directory,
when using this mode. Therefore, after "pip installing" any library (including
from remote orlocalsources), you could follow that up by runningpyMkDocsagainst itby import name!As a bonus, when using this mode, "magic comments" (using syntax defined for this
specific tool) will be processed if placed within such an__init__module being
scanned. This is used to dictate how the markdown files / site pages will be named
and ordered, along with what content is generated.Let's look at an example "magic init" file...example/src/init.py:"""This library is very impressive... :)"""# docs > Introduction.md# docs : __doc__#------------------------------------------------------------------------------# docs > Mini.md""" docs : proseHere is some preamble text for the page..."""from.functionsimportmini,MIN_SIZE""" docs : proseClosing comments on these functions..."""#------------------------------------------------------------------------------# docs > Shark.md""" docs : proseThis page is devoted to the **Shark**."""from.class_and_functionimportShark,maxi#------------------------------------------------------------------------------# docs > nullfromosimportabc#------------------------------------------------------------------------------# docs > Config Parser.md""" docs : virtualfrom configparser import ConfigParser"""This__init__file naturally controls what is accessible via the Python
import system when a client executesimport src(assuming that package can
be found). The items defined in this file are imported by a Python interpreter.
They are also auto documented when scanned by this tool, along with processing
the "magic comments" the interpreter ignored.The following magic comments commands may be included in your__init__module.START WRITING:# docs > [Page Name].mdComment lines which start with this, indicate a starting point
for what is to be written to a given markdown file. That file/page will be named
by what follows thatdocs >prefix. Note that the source content indexed and
included in the resulting file may come fromanyimportable module / package
on your system - not just your source!PROSE:""" docs : proseThis markdown appears where ever you want in the current document."""Following this comment pattern, "write" this markdown to the current document.PACKAGE DOCSTRING:# docs : __doc__Inject the the package doc string into the current document.DISCARD:# docs > nullDiscards the documentation for whatever source code follows.VIRTUAL CODE:""" docs > virtualis_virtual_code_cool = True"""Following this comment pattern, the parsing / object inspecting performed
by the tool will act as though the virtual code were actually present,
but without it having to truly be included in your project.
This provides a means to create documentation in a completely open ended manner
that is is not tightly bound to any literal source.Minimal project layoutbefore pyMkDocs:src/
     ...         # Other python files or foldersafter pyMkDocs:mkdocs.yml      # The configuration file.

 src/
     ...         # Other python files or folders

 docs/
     index.md    # The documentation homepage.
     ...         # Other markdown pages, images and other files.

 site/           # The static site ready to be hosted
     index.html
     ...Custom ContentpyMkDocs is not limited to only generating a site from scratch. Instead, it can
be dynamicallyintegratedwith your custom content.  Once you know how, it's
easy to add your own pages, to add more
MkDocsextensions,
to addplugins,
modify the sitethemeand more!Update ModeThe easiest way tostartan pyMkDocs project is to first allow the tool to
create a basic site for you.  After that, you may edit themkdocs.ymlfile
which was generated.  When the tool is run again subsequently, it will detect
the presence of that prior configuration, and then operate in "update mode".In "Update Mode", the only part of themkdocs.ymlwhich pyMkDocs will
modify is that found within the "Reference" section.  Anything else which you
customized will be fully preserved and respected while MkDocs regenerates the
site.To learn more about how you may modify themkdocs.ymlfile, see theMkDocs Configuration Guide.Hybrid ModeAn alternative "Hybrid Mode" has also been provided. This a middle ground
between starting from scratch or operating as a pure "update".To use this method:Remove an existingmkdocs.ymlfile (if applicable)Create adocsfolder (if one does not exist)Addyour ownMarkdown files to thedocsfolderRun pyMkDocs!The result of this will be similiar to creating a whole new site, accept
your pre-existing Markdown files will be used to generate site pages
and they will be automatically added to the top level of your table of contents!Home PageWhen a vistor first browses to the site, its "Home" page will be displayed.
This page is created from a Markdown file namedindex.md(named like a
default website page:index.html).If this file does not exist in yourdocsfolder, pyMkDocs will generate
a simple placeholder for you. To revise the content of this page, simply
edit, or replace, theindex.mdsource.Attribute DocstringsThe formal standards for Python docstrings are defined inPEP-257.
They do NOT include "attribute docstrings". There is, therefore, noofficialmeans
to document how to use class and module attributes. The primary reason for this
is because a consensus could not be arrived upon as to what the cleanest
means would be for developers to employ such a standard in practice. Following
the rules for how this is done with modules, classes, and functions
(adding triple double comments after the object signatures), seemed excessive
or confusing to some. Further, there is a belief that attributes should be
"self documenting", by simply using good names for them.That said, it has been suggested thatunofficialdocumentation generators
(such as this) may still wish to adhere to the standards proposed in therejectedPEP-224orPEP-258regarding attributes. So, pyMkDocs recognizes those conventions and processes
such comments when generating documentation.Recommended Function DocstringCode:deffun(arg1:int,arg2:str='Hello World!'):"""Description of your function**Parameters**> **arg1:** `int` -- Description of argument `arg1`.> **arg2:** `str` -- Description of argument `arg2`.**Returns**> `str` -- Description of returned object."""returnarg2+str(arg1)Screenshot:Want more?Check out the example source. There, you will find tons of fancy elements you
can now instantly add to your documentation, leveraging the power of manyMkDocsextensions!Now what?Once you have the source generated for a static website to display your amazing
documentation, how do you make that available to your users / target audience?Well you may, of course, setup website hosting in any number of manners (which
are all well beyond the scope of this document!). With that done, you could
simply upload the files there. That said, a very notable option for this
specific purpose, which is free, fast, and easy, is to useGitHub Pages.With GitHub Pages, you may create anewGitHub repository dedicated to the
site, or you mayadda GitHub Pages site to anexistingrepository (e.g.
your project source). Arguably, the latter makes more sense if the code you are
documenting is already on GitHub, or you intend to post it there. For more on
this see:Creating a GitHub Pages siteNote that GitHub Pages allows you to serve your site from either therootof
the repository, or a sub directory nameddocs. There is no option to define
this path yourself, or to use a directory namedsite.While GitHub Pages supports Markdown based sites, and can therefore use adocsdirectory with such content, it will then convert that to html via a
seperate mechanism from what you've already produced with MkDocs. If you would
like to add a GitHub Pages site to anexistingrepository, it is doubtful you
would want it on theroot, so in order to post your site as it appears locally,
you will need to place what is normally the "site" content in thedocsdirectory. Thankfully, this is easy to resolve! Simply rename your folders
and add the following lines to yourmkdocs.yalmfile:docs_dir: docs_src
site_dir: docspyMkDocs will then auto generate Markdown into adocs_srcfolder and
MkDocs will generate the website content withindocs. Problem solved.