Importers


No articles match the selected filter.

Importing Documentation

The Reference section of Presidium should be reserved as a low-level reference for users. Typical components documented in the Reference section may include a client library or API specification. The process of importing documentation involves parsing a reference source and generating articles that are included in the generated site.

Where possible, reference documentation should be generated to ensure that your documentation is in sync with the system being documented.

Presidium supports the following documentation sources:

For other sources that do not yet have an importer, documentation can be embedded into references.


Swagger

Presidium includes a Java-based tool (presidium-swagger, based on Swagger2Markup) to import your API’s Swagger into your Presidium documentation.

  1. Add the presidium-swagger dependency to your site’s package.json or run npm install --save presidium-swagger.
  2. Add a script that invokes the tool.
  3. Run npm run import-swagger whenever you need to update your API documentation.
{
    "scripts" : {
        "import-swagger" : "presidium-swagger"
    },
    "devDependencies": {
        "presidium-core" : "#.#.#",
        "presidium-jsdoc" : "#.#.#"
    }
}

Example:

$ npm run import-swagger -- -u <url> -d <path> -t <string>

The following options are available for presidium-swagger:

Option Description
-d,–directory path The destination directory in which to save the generated documentation. (Default is ‘./docs’.)
-h,–help Displays this help.
-s,–sourcepath path Swagger source path.
-t,–title string The title of your docs folder. (Default is directory name supplied with ‘-d’.)
-u,–sourceurl url URL to your Swagger Json file.

Javadoc

Presidium can import Java source code comments using the Presidium Doclet implementation. Imported documentation will be included in the menu and sitemap.

To import javadoc, use the presidium-javadoc package.

  1. Add the presidium-javadoc dependency to your site’s package.json.
  2. Add a generation script that parses the provided <src-path> directory and <packages> and generates Markdown in your content/_reference section.
  3. Run npm run import-javadoc-api when you need to update your source documentation.
{
    "scripts" : {
        "import-javadoc-api" : "presidium-javadoc -s <src-path>"
    },
    "devDependencies": {
        "presidium-core" : "#.#.#",
        "presidium-javadoc" : "#.#.#"
    }
}

The following options are available to presidium-javadoc:

Option Description
-d,–directory path The destination directory in which to save the generated documentation. (Default is ‘./docs’.)
-h,–help Displays this help.
-p,–subpackages package1:package2:... Packages to generate documentation from. (Default is all.)
-s,–sourcepath path Java source code directory.
-t,–title string Reference title. (Default is ‘javadoc’.)
-u,–url foo/bar/{title-slug} Section url. (Default is ‘reference/javadoc’.)

Alternatively, you can use the Doclet within an existing build workflow such as gradle using the javadoc-plugin.


Jsdoc

Presidium includes a template-based tool, presidium-jsdoc, based off of Jsdoc) to import Javascript comments into your Presidium documentation.

  1. Add the presidium-jsdoc dependency to your site’s package.json or run npm install --save presidium-jsdoc.
  2. Add a script that invokes the tool.
  3. Run npm run import-jsdoc whenever you need to update your API documentation.
{
    "scripts" : {
        "import-jsdoc" : "presidium-jsdoc"
    },
    "devDependencies": {
        "presidium-core" : "#.#.#",
        "presidium-jsdoc" : "#.#.#"
    }
}

Example:

$ npm run import-jsdoc -- -s <path> -d <path> -t <string> -p <path>

The following options are available to presidium-jsdoc:

Option Description
-d,–directory path The path to the output directory in ./content (for example, ./content/_reference/mydocs).
-h,–help Displays this help.
-p,–path path The path from which static files are served (for example, ./media/import/mydocs). Default is ./media/jsdoc/<title>.
-s,–sourcepath path The path to the project’s source.
-t,–title string The title of the output folder. Default is the directory name supplied with -d if no package information is found.

Embed

A fallback approach to importing generated documentation is to embed documentation in an iframe. This approach is not recommended because items are not indexed or available on the main menu. However, it will work for certain cases when an importer is not yet available.

When possible, use a simple template when embedding documentation in an iframe.

To include documentation in an iframe:

  1. Generate the static site documentation for your component.
  2. Put the documentation in the /media folder so that it’s statically served. The Presidium convention is to place it under /media/import/{my-reference}.
  3. Add a reference article to the Reference section:

---
title: My Reference
---

# foo.bar

<div>
    <iframe
            src='/media/import/{my-reference}/foo/bar/package-summary.html'
    </iframe>
</div>

You can create multiple Markdown files for different components as required.


© Copyright 2018 SPAN Digital

Generated on Nov 21, 2018