dookumentation

https://pypi.python.org/pypi/dookumentation

Screenshots

Features

• KISS, Takes a full path to anything, a file or a folder, parse and generate multiple documentation formats.
• Standalone, uses ONLY Standard Libraries, built-in on Python 3.
• Async, does not Block or Slows down even with large amount of files and folders to process.
• Watch, Watch for changes on files re-process only the changes, you code and forget about Documentations.
• Zero Config, No configurations, No settings, No *.yml or makefile files required to work, ever.
• Single-File, everything is just 1 file, with PEP-8, Lint and other Python Best Practices, very readable.
• Python3 ready, it will only work with Python >= 3, instead of soon to be deprecated (year 2020) python2.
• Unicode ready, it should handle correctly any kind of character that UTF-8 can support without escaping.
• Plugins, write your own plugins with native unrestricted Python 3, plugins are single file plain text.
• Templates Custom, Custom Templates ARE plugins, write one get two at the same price.
• Export to Anything, Templates are Plugins and are for Exporting to any kind of format you need.
• Serve + Live-Reload, HTTP Web Server from local computer to the network, with Live-Reload.
• Fades, Built-in Fades support by default.
• YouTube, Built-in Youtube support, Youtube links on DocStrings get Automagically Embedded.
• Minimalism, do 1 thing do it awesome, is tiny and simple, K.I.S.S., its < 1.000 lines.
• Scripting, Execute custom Scripts (eg. Bash *.sh) After and Before the processing of files and folders.
• Recursive, it can work recursively processing whole project folders at once.
• MetaData + Statistics, Parse, Collect and Display nice MetaData and Statistics of your work.
• Cross-reference Links, Automagically determines a word is referring to Python Library and Link to its Documentation.
• Download/Export, Get a JSON file or MarkDown file directly from the generated HTML documentation.
• ProcessName, Sets its own Process name and show up on Process lists, like htop and System Monitors.
• Updates, Can optionally check for updates for itself, from the Internet.
• Smooth CPUs, Sets Smooth CPU usage, good for portable devices on battery.
• Colored Logging, Colors on the logs, log file for troubleshooting, SysLog support.
• Single Instance, via Sockets.
• Your Feature or idea here...

Input Formats

• *.py Python source code file, single file or whole folders recursively.
• *.pyw Python source code file for MS Windows, single file or whole folders recursively.
• *.PYZ Python source code file ZIP Compressed, single file or whole folders recursively. Planned for future, not supported yet.
• Your Input Format here...

Output Formats

• HTML5, Material Design, Minified, Download/Export JSON and MarkDown from the HTML Docs *.html
• MarkDown, GitHub Compatible, Pretty-Printed *.md
• RST, ReSTructuredText, Nikola Compatible, Pretty-Printed *.rst
• JSON, Pretty-Printed, JavaScript Compatible *.json
• ODT, ODF ODT Document, LibreOffice Compatible *.odt
• eBook, Compressed eBook with HTML5 Documentation, ePub3 compliant, optional via --ebook parameter *.epub
• ZIP, Compressed ZIP with HTML5 Documentation inside, optional via --zip parameter *.zip
• SVG for the Web, HTML5 <svg> standalone document, Pretty-Printed, via single-file provided plugin *.svg
• XML, generic XML, Pretty-Printed, via single-file provided plugin *.xml
• TXT, Unformatted Plain Text, Pretty-Printed, easy to parse from scripts, via single-file provided plugin *.txt
• Infinite?, via third party Do-It-Yourself single-file plugin
• Your Output Format here...

Usage:

dookumentation.py file.py

dookumentation.py /path/to/folder/

Plugins Usage:

• Download and save the plugins to /doc/plugins/, thats all.

Example: If your plugin is named template.xml then save it to ./doc/plugins/ being the actual relative path as ./doc/plugins/template.xml, on the next run, your plugin will be used.

Folders Hierarchy

• This folder structure will be created automatically by Dookumentation if it does not exist.
• Relevant directories and files with Description:

/                   "This is the relative path to the project being Documented (eg. *.py)."
│
└── doc/
    ├── html/            "HTML Documentation files are saved here (eg. *.html)."
    │    ├── css/        "Custom CSS StyleSheets files are read from here (eg. *.css)."
    │    ├── js/         "Custom JavaScript files are read from here (eg. *.js)."
    │    ├── favicon.ico "Custom FavIcon.ico file are read from here (eg. favicon.ico)."
    │    └── index.html  "Index main page are saved here (eg. index.html)."
    ├── md/              "MarkDown Documentation files are saved here (eg. *.md)."
    ├── rst/             "ReSTructuredText Documentation files are saved here (eg. *.rst)."
    ├── odt/             "ODT ODF Documentation files are saved here (eg. *.fodt)."
    ├── json/            "JSON Documentation files are saved here (eg. *.json)."
    ├── plugins/         "Template-Plugin files are read from here (eg. SVG, XML, etc)."
    ├── html.epub        "Compressed eBook Documentation from HTML5 (if --ebook is used)."
    └── html.zip         "HTML Documentation on Compressed ZIP file (if --zip is used)."

Install

PIP: (Recommended!)

sudo pip3 install dookumentation

PIP from Git: (Not Recommended)

sudo pip3 install git+https://raw.githubusercontent.com/juancarlospaco/dookumentation/master/dookumentation.py

WGET: (Not Recommended)

sudo wget -O /usr/bin/dookumentation.py https://raw.githubusercontent.com/juancarlospaco/dookumentation/master/dookumentation.py
sudo chmod +x /usr/bin/dookumentation.py
dookumentation.py

MANUALLY:

• Save this file and run it with Python3.

Why?:

• Pycco/Docco: Abandonware since ~2012, Broken on Python3, Broken Unicode, very Limited and Uncomplete port of Docco, Docco may be Ok for CoffeeScript, but Pycco is too unfinished, is for single-files, no Watch, no LiveReload.
• PyDoc/ePyDoc: Ugly as hell, old html Markup, hard to style its CSS, html only output, is for single-files (?), no Watch, no LiveReload.
• MkDocs: Dont generate Docs from Source, just build HTML from MD, lots of Dependencies, config files required, manual boilerplate required, html only output.
• Sphinx: Makefiles Ain't Nobody Got Time For That, imports all the modules to be documented, Lots of Manual Configuration required, old html Markup, Ugly by default, Dont generate Docs from Source by default, lots of Dependencies, manual boilerplate required, you still need to mess around with PanDoc and Plugins for other outputs formats than HTML, no Watch, no LiveReload.

Requisites:

• Python 3.x (or PyPy 3.x, or Python Nightly)

Optionals:

• PyLama
• Pygments
• LiveReload

Coding Style Guide:

• Lint, PEP-8, PEP-257, PyLama, iSort must Pass Ok. pip install pep8 pep257 pylama isort
• If theres any kind of Tests, they must Pass Ok, if theres no Tests, its ok, if Tests provided, is even better.
• PEP-0257 Official Python Docstring Style Guide

Contributors:

• We need Designers, Web-UI, Front-End Dev for help making Templates look Awesome !!!.
• Please Star this Repo on Github !, it helps to show up faster on searchs.
• Ad-Hocracy Meritocracy: 3 Pull Requests Merged on Master you become Repo Admin. Join us!
• Help and more Help and Interactive Quick Git Tutorial.

Ethics and Humanism Policy:

• May this FLOSS be always Pristine and Clean, No AdWare, No Spamm, No BundleWare, No Infomercial, No MalWare.
• This project is LGBTQQIAAP friendly.

Licence:

• GNU GPL Latest Version, GNU LGPL Latest Version, GNU AGPL Latest Version, MIT Latest Version, any Licence YOU Request via Bug Report.

Donate, Charityware :

• Charityware is a licensing model that supplies fully operational unrestricted software to the user and requests an optional donation be paid to a third-party beneficiary non-profit. The amount of donation may be left to the discretion of the user.
• If you want to Donate please click here or click here or click here or click here or click here or click here or click here