Documentation

Contributors guide for the Nephio documentation

Framework

The Nephio documentation is built with the .md / Hugo / Docsy / Netlify framework.

  • .md: The documentation itself is written in Markdown (,md) with some Hugo and Docsy related extensions. The .md files are stored and managed in a Git repo in nephio-project/docs.
  • Hugo: Hugo is used to render the documentation fo static html pages.
  • Docsy: Docsy is a theme for Hugo what we use to provide the basic structure and look and feel of the documentation.
  • Netlify: Netlify is a service to host documentation. We are hosting the Nephio
    documentation from here.

Creating issues

Documentation issues are handled in the nephio-project/nephio repository’s issue handler. Add the area/docs and the documentation labels to the issues created for the documentation.

Style guide

  • Use US English in the documentation

  • Do not add manually a table of contents to the documents. Hugo and Docsy takes care of this.

  • Do not use H1 (#) headers in the documents. Docsy generates a H1 header to every document consistent with the title of the document. Start the headings with H2 (##)

  • Use the built in alerts for notes and alerts

    {{% alert title="Warning" color="primary" %}}
This is a note.
{{% /alert %}}

    {{% alert title="Warning" color="warning" %}}
This is a warning.
{{% /alert %}}

  • Colors to be used when creating figures are here

  • If you add any commands to the content inline surround the comand with backticks (` `), like `ls -la`

  • Do not surround IP addresses, domain names or any other identifyers with backticks. Use italics (* *) to mark any inline IP address, domain name, file name, file location or similar.

  • Whenever possible define the type of code for your code blocks

    • ```bash for all shell blocks
    • ```golang for all Go blocks
    • ```yaml for all YAML blocks
    • ``` yang for all YANG blocks
    • a full list of language identifyers is available here

  • Do not add any TBDs to the documentation. If something is missing create an issue for it

How to contribute

Follow the Nephio contribution process, based on GitHub pull requests and Prow. Contributions to the Nephio documentation require the Nephio CLA.

Build your environment

Following the description here.

Tests before submitting a pull request

  • Build and deploy the documentation locally
    • run hugo serve
  • Build in a same way as Netlify is doing it
    • run hugo --gc --minify
  • Check links
    • Install and run linkspector 
      npm install -g @umbrelladocs/linkspector
linkinspector check -c .linkspector.yml

Checks before submitting a pr

FAQ

  1. How do I check the documentation links on the documentation before I check in my changes?

    Install and run linkspector

    npm install -g @umbrelladocs/linkspector
linkinspector check -c .linkspector.yml