Tech Docs

The TechDocs feature is installed by default with Red Hat Developer Hub. TechDocs provides a central and standardized system for creating, finding, and reading technical documentation.

  • Docs-as-Code: Documentation source files are stored alongside code in the same repository, making it easier and more obvious for developers to update documentation along with code.

  • Centralized, but Distributed: TechDocs centralizes access to documentation within the developer portal, while distributing the documentation source files across repositories owned by the teams that develop, use, and maintain them.

  • Automated Rendering and Publishing: TechDocs (usually) generates static HTML from Markdown source files. This integrates into CI/CD processes to automate publication. Generated documentation is collected, accessible, and, most importantly, searchable alongside code, repos, APIs, and services in Red Hat Developer Hub.

How it works

TechDocs assumes documentation is a part of nearly every Component in a Red Hat Developer Hub Catalog. At a high level, TechDocs fetches, renders, and presents that documentation with the process enumerated below. Definitions and details follow in subsequent sections.

  1. Docs reside with Component source in the Component’s repository, conventionally in Markdown format in a directory named docs.

  2. A repository has a build process, such as a pipeline or a GitHub action, triggered when changes happen. Usually this is when a commit changes the relevant source repository branch.

  3. Part of that pipeline generates static HTML from the Markdown source found beneath /docs and stores the result in a location accessible to TechDocs. This location is conventionally an AWS S3 bucket, or other storage presenting the S3 API.

  4. The TechDocs plugin in Red Hat Developer Hub publishes the rendered documentation, making it available throughout Red Hat Developer Hub: in the top level left navigation Docs item, from links within its Component, and in other relevant locations.

  5. Edit icons on each document link back to the document source in the Component repository’s docs directory. Developers edit documentation using repository service web editors, OpenShift DevSpaces, their favorite IDE, or any text editor, and add their changes to the repository through their team’s usual code review/test/commit process. This is commonly represented by the generation of a Pull Request (PR) in services like GitHub or GitLab.

  6. When such changes are committed, TechDocs processing returns to Step #2, above.

Out of the box in Red Hat Developer Hub

The default installation of Red Hat Developer Hub simplifies TechDocs processing with a lightweight local TechDocs instance. This provides complete TechDocs documentation editing, automatic rendering, and centralized discovery and reading without immediately setting up external requirements such as storage and pipelines. In this configuration TechDocs writes rendered documentation to ephemeral storage. This means generated HTML will not survive restarts of the Developer Hub Pod without further arrangement. In practice, for most introductory use this is not a problem, because documents are rendered again from their Markdown source and the cache of static HTML rebuilt on demand.

Note, however, that Red Hat Developer Hub documentation clearly states that the included lightweight TechDocs configuration is not intended for production use. The second TechDocs lab constructs an example production deployment.

Builder, Generator, Publisher

In the appearance customization lab, you worked in the OpenShift Project brand-rhdh and created a new Red Hat Developer Hub instance. In this lab, you’ll begin with a provided Developer Hub already running in a the tssc-dh Project. This instance is configured with the default lightweight TechDocs process.

  1. In the OpenShift Web Console, Select the Administrator perspective, navigate to Workloads > ConfigMaps, and ensure the tssc-dh Project is selected in the project selector drop-down.

  2. Find and click on the tssc-developer-hub-app-config ConfigMap to view the the key parts of the TechDocs process configuration of this instance of Red Hat Developer Hub.

    The excerpt below shows the TechDocs process configuration defined in the tssc-developer-hub-app-config ConfigMap in the tssc-dh Project.

    [...]
    techdocs:
        builder: local
        generator:
            runIn: local
        publisher:
            type: local
[...]

techdocs.builder

The TechDocs builder value determines whether settings for a resident TechDocs build process are available. With builder: local, the generation and publication steps may also be performed by TechDocs. If builder is set to external, TechDocs assumes documents are generated and stored elsewhere and does no processing of documentation source, instead expecting to fetch and serve fully baked static HTML with the publisher component alone.

techdocs.generator

The configured generator compiles documentation source into presentation HTML. In the default configuration, generator's runIn attribute is local. The setting of builder to local already implies that TechDocs will itself retrieve documentation source from entity repositories and convert it to HTML. Here, local sets the generator to runIn the same process space as TechDocs.

The value of generator runIn may instead be docker, an anachronistic misnomer that refers to running the generator in its own Linux container. This is seen for example in development setups running directly on a host and using a generator container for convenience and isolation. Your Red Hat Developer Hub instance is already running in a container, inside a Pod, as part of a Deployment on an OpenShift cluster. Setting generator to runIn the local context avoids running a container inside of a container without due cause.

The TechDocs generator is named and somewhat structured for modularity, so that the generator may be replaced by other implementations at specific sites today or in general releases in the future. This allows the possibility of converting documentation source in different formats in different ways and into different output products. Today, the TechDocs generator is almost always mkdocs-techdocs-core, a plugin for the underlying MkDocs site generator. This combination takes Markdown source as input and outputs static HTML.

techdocs.publisher

The name publisher is somewhat overloaded. As the name implies, the publisher serves generated HTML documentation to Developer Hub users for reading in a web browser. When builder is local, the publisher also handles writing prepared HTML to storage, later fetching it back to serve it. The value of publisher.type determines where the publisher stores generated HTML. When type is local, publisher writes HTML to and serves it from storage locally available to the RHDH process. As shown above, the default lightweight TechDocs is configured with techdocs.publisher.type: local. The publisher type may instead be one of a few external storage providers, including awsS3. External storage configuration is part of the the second TechDocs lab.

Developer Experience: Find, Read, Edit Documentation

The lightweight TechDocs process included in Red Hat Developer Hub provides exactly the expected view/edit/build/view cycle for component documentation creators and users. While functionally equivalent, the default deployment is not recommended for production because it may not scale to many documents, repositories, or developers.

The build process configured entirely for the local TechDocs context works like this:

  1. As always, documentation source is stored alongside application code in the component repository.

  2. A developer edits documentation source and commits changes to the component repository. In the default arrangement, this does not immediately trigger the documentation build process. The new document will be generated on demand when its HTML representation is next requested.

  3. The developer’s teammate looks up TechDocs for the component. TechDocs checks if document source has changed since the HTML was last generated. If it has, the mkdocs-techdocs-core MkDocs plugin drives the MkDocs site builder in Developer Hub’s techdocs-backend module to render the Markdown source into HTML. The new HTML representation is made available to the teammate in the following series of display element updates:

View the Latest Doc

A new request for a document triggers TechDocs to check for updates in the document’s source repository.

When the source has changed, techdocs-backend rebuilds the HTML representation and the page presents a banner. First, with a blue outline, the banner indicates the update is in progress.

builddoc

When generation is complete, the banner dons a green outline and asks the viewer to please refresh.

plsrefr

Clicking the Refresh link reloads the page with the latest HTML.