Corto documentation framework
Switch branches/tags
Nothing to show
Clone or download
Latest commit 2c539b8 May 9, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE Initial commit May 9, 2018
README.md Add & fix links May 9, 2018

README.md

cortodoc

Cortodoc is an easy to use framework that generates HTML-based documentation from markdown files. An example of documentation generated by cortodoc can be found here: https://corto.io/doc/guide.html.

In addition to features provided by markdown, cortodoc comes with a number of custom features:

  • highlight notes, warnings and console commands
  • syntax highlighting for popular languages
  • doxygen support (example)
  • code generation from corto model files

** This document is a work in progress. Some sections may refer to features that are not yet implemented, and some links may not yet work **

Installation

[cortodoc installation instructions]

To install cortodoc, make sure that bake is installed, and the corto runtime and tool are installed to your machine. Try running the following commands on your machine to verify if you meet the prerequisites:

bake env
corto --version

If both commands run without errors, you can proceed with the cortodoc installation. If not, this command will install the prerequisites:

curl https://corto.io/install-bake | sh

Run the bake and corto commands again to verify that the installation was successful, and you can access both commands from the terminal.

Now, run this command to install cortodoc:

curl https://corto.io/install-cortodoc | sh

This will download and install the cortodoc repositories to your machine. After the installation is completed, you can start using cortodoc!

Repositories

The cortodoc framework implementation can be found in the following repositories:

Repository Description
driver-tool-doc The tool that is invoked when the corto doc command is ran
driver-gen-doc-doxygen Doxygen to markdown generator
driver-gen-doc-html HTML generator for cortodoc objects
driver-ext-md Markdown parser that stores markdown as cortodoc objects
doc Documentation for cortodoc

Getting started

[quick start for new users]

To generate documentation, a markdown file is required first. Any markdown file can be parsed by cortodoc. The following command will generate HTML from a markdown file called README.md:

corto doc README.md

After the generation has completed, the directory in which the command was executed will now contain an html directory, which contains the generated HTML documentation.

Manual

[everything you need to know about cortodoc]

Generating from a markdown file

The corto doc tool (https://github.com/cortoproject/driver-tool-doc) is a simple front-end for the cortodoc framework. It accepts a single argument, which is a markdown file, for which it will invoke the cortodoc HTML generator. The following command generates HTML for a file called README.md:

corto doc README.md

The output of this command will be stored in a newly created html folder. The html folder is self-contained, with all the required JS, CSS and HTML stored inside.

When no argument is provided to corto doc, the tool will look for a doc folder, and generate HTML for every markdown file in that directory.

Generating from doxygen

Cortodoc supports generating HTML from doxygen comments in bake projects. For this to work, doxygen must be installed to your machine, and the doxygen command must be available from the terminal.

The Doxygen HTML generation first generates a Doxygen XML file, using the doxygen tool. From the Doxygen XML, a markdown file is generated. From this markdown file, the HTML is generated, using the default markdown-to-HTML generator. This whole process is automated by the corto doc tool, but it does require some configuration in the project.json file and project header files to set it up.

Doxygen generates XML files for each file in the project that contains Doxygen comments. To prevent generating a large number of markdown and HTML files, cortodoc can combine output from multiple Doxygen XML files into one or more markdown files. Which Doxygen documentation ends up in which markdown file is fully customizable.

To set this up, first the header files for which cortodoc documentation is going to be generated should include the following section:

/** @file
 * @section my_api Short single-line description of the file contents.
 * @brief Long multi-line description of the file contents.
 */

The brief property is optional. The @file and @section properties are mandatory. If these do not appear in the header file, no documentation will be generated. The first argument of the @section property must be the header filename without the file extension.

Now the documentation framework must be told which source files to generate to which markdown files. This is configured in the project.json file. Here is an example:

{
    "id": "my_package",
    "type": "package",
    "value": {
        "doxygen": [{
            "title": "My API Description",
            "chapters": [ "my_api" ]
        }]
    }
}

This configuration will create a single markdown file in the doc directory called My_API_Description.md, which will contain the Doxygen-generated documentation from the my_api.h header file. The chapters property can contain any number of header filenames. Their names must match with the name provided to the @section property, and the name of the header file.

The configuration section can generate multiple markdown files in a single generation. To enable this, simply add more elements to the doxygen array, like so:

{
    "id": "my_package",
    "type": "package",
    "value": {
        "doxygen": [{
            "title": "C API",
            "chapters": [ "my_c_api", "c_datatypes" ]
        }, {
            "title": "C++ API",
            "chapters": [ "my_cpp_api", "cpp_datatypes"]
        }]
    }
}

After the generation has completed, the markdown files that were generated from Doxygen documentation are cleaned up from the doc folder. If the doc folder contained markdown files that were not generated by doxygen, they will not be touched by the corto doc tool.

Markdown extensions

Descriptions

The cortodoc framework can add short descriptions to the headers in the index. These provide hints to the user about what a section in a document contains, without having to scroll to that section. Descriptions must be the first paragraph in a header, and must be enclosed within [ ]. An example:

## Getting started
[instructions for a new user]

The actual text for getting started.

Currently, cortodoc only parses descriptions for level-2 headers. Descriptions at other levels are parsed, but no HTML is generated for them.

Special documentation blocks

Syntax highlighting

Generate multiple files to single location

Customize cortodoc template

Authors

[who built cortodoc]

  • Johnny Lee Othon - Initial work
  • Sander Mertens

Legal stuff

[cortodoc licensing]

Cortodoc is licensed under the GPL3.0 license.