The Documentos system is a way to take a series of Markdown files that can be nested or not and transforms them to HTML or PDF documents. The goal of the system is to provide a tool that can take a set of documentation along with its localizations (translations to other languages) and provide a seamless method to transform to other formats in a consistent and reproducible manor.

It provides a common way to implement documentation in a text based format while retaining the power to transform the documentation to other formats. It makes use of TOML configuration files, and Pandoc and Python to transform Markdown formatted documents into any of the other formats provided by Pandoc. This system has a heavy focus on HTML transformations.

The goal is to provide a plain text mechanism with a very light markup for software documentation. The idea is to make the documentation so that it can live along side the source code in the repository. Changes in the source code that prompt documentation revisions can live side-by-side in the repository. In fact, it is entirely possible to institute a code-review process for documentation revisions and updates.

This tool includes a sample documents folder that can help you understand how the system works. Simply clone the repo and issue the make html in the repo if you are using Linux.

$ make html

Clone the git repo:

$ git clone [email protected]:TroyWilliams3687/documentos.git

For full details, see the Documentation Repository note. It will walk you through the entire process.

You can use the Makefile to create the virtual environment and install all requirements automatically:

$ make venv

Otherwise you will have to create the virtual environment manually and install the dependencies traditionally after activating the environment.

Activate the virtual environment that you want to install it too.

On Windows, using powershell:

$ .\.venv\Scripts\activate.ps1

On Linux, for most causes you can simple using the Makefile to build the system. If you need to activate the virtual environment:

$ make shell

Or manually:

$ . .venv/bin/activate

Use pip to add the repository manually to the virtual environment where you want to use the tools.

$ python -m pip install git+https://github.com/TroyWilliams3687/documentos

You can use the code in the documentos, by importing it into your module:

import documentos

For system commands see commands.

The documentation can be found here. Interesting information:

• System Information
• Pandoc
• Python
• Repo Setup
• TOML

MIT