layout-3layout-6layout-1layout-top
layout-toplayout-6layout-1

Make a Larger Contribution

So you have more extensive comments or want to provide new content? Then there is a bit more that you need to understand to provide feedback of this type.

You need to set up a local environment for the documentation, perform your edits or create your new content there, and then submit it all through a pull request against the CumulusNetworks/docs repository on GitHub.

To get started:

Install Hugo

The first step is to install Hugo:

  1. Go to https://github.com/gohugoio/hugo/releases/tag/v0.82.0.

  2. Select the relevant extended package based on your operating system:

    • hugo_extended_0.82.0_Linux-64bit.deb
    • hugo_extended_0.82.0_Linux-64bit.tar.gz
    • hugo_extended_0.82.0_macOS-64bit.tar.gz
    • hugo_extended_0.82.0_Windows-64bit.zip

You must use the extended version of Hugo to support our use of SCSS stylesheets.

  1. Decompress and install Hugo from the download.

  2. Verify Hugo is installed and running.

    From a terminal window, run hugo version:

    <computer>:<username>$ hugo version
hugo v0.82.0-9D960784+extended linux/amd64 BuildDate=2021-03-21T17:28:04Z VendorInfo=gohugoio

Clone the Documentation Repository

The next step is to obtain a local copy of the Cumulus Networks Documentation Repository:

  1. Create a directory where you want to store the documentation files.

  2. Navigate to https://github.com/CumulusNetworks/docs.

  3. Make sure the Branch is on stage, and then click Clone or download.

  4. Copy the HTTPS URL.

  5. Return to your directory in the terminal window and type git clone.

  6. Paste in the URL, and press Enter.

    <computer>:<cndocs-repo> <username>$ git clone https://github.com/CumulusNetworks/docs.git

When it is done cloning, your directory should have a copy of all of the source files.

Run the Local Server

And the final setup step is to validate that you can view your local copy of the documentation repository using Hugo:

  1. From your terminal window, navigate to the docs subdirectory.

  2. Start the hugo server by running hugo server --baseURL localhost:1313.

    You should see output similar to this:

    <computer>:docs <username>$ hugo server
Building sites...

                   |  EN
-------------------+-------
  Pages            |  769
  Paginator pages  |    0
  Non-page files   | 2003
  Static files     | 1925
  Processed images |    0
  Aliases          |    0
  Sitemaps         |    1
  Cleaned          |    0
   
Built in 6294 ms   
Watching for changes in /Users/<username>/<cndocs-repo>/docs/{content,data,static,themes}
Watching for config changes in /Users/<username>/<cndocs-repo>docs/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

  3. In the address field of a web browser, enter http://localhost:1313.

    When you make and then save changes to the source Markdown files, the updates are shown here.

    If the page does not appear to be updating, you may need to stop the Hugo server (press Ctrl+c) and restart it using hugo server --baseURL localhost:1313 --gc to rebuild the site without using cached data.

You are now ready to edit the documentation or create a new topic. Refer to Adding New Content.

Conform to House Style with Vale

The documentation uses Vale as a linting tool to keep the writing consistent. Think of it as an AI editor you invoke at the command line.

Install Vale

To get started, install Vale. Run the following command in a terminal:

$ brew install vale

> choco install vale

$ docker pull jdkato/vale

You need homebrew to install on MacOS or Linux, and choco to install on Windows.

Run Vale

Before you run Vale, pull the latest version from the stage branch, then make sure your local checkout has the /utils/.vale folder.

Run Vale from the root of your local checkout:

$ vale --glob='!*{foss,rn}.md'  --config utils/.vale/.vale.ini content/cumulus-linux-43

The command above uses the following arguments and options:

  • The --glob regular expression instructs Vale to ignore the foss.md and rn.md files; Vale does not check the release notes or t the Cumulus Linux open source software license page.
  • The --config utils/.vale/vale.ini tells Vale where to find its configuration file.
  • The content/cumulus-linux-43 is the folder Vale is going to check. Vale recurses through every folder below it, so if you run it on the top level content folder, it checks every single page for every version and product.

Vale returns output like the followings sample:

pete$ vale --glob='!*{foss,rn}.md'  --config utils/.vale/.vale.ini content/cumulus-netq-40
...
 content/cumulus-netq-40/Manage-Configuration/Provision-Network-and-Devices/Switch-Lifecycle-Management/CL-Upgrade-LCM.md
 219:104  error  'Mellanox' should reference     NVIDIA.Branding 
                 NVIDIA Networking or NVIDIA                     
                 Spectrum                                        

 content/cumulus-netq-40/Get-Started/NetQ-Basics/NetQ-Components.md
 35:60  warning  'bare metal' is the house       NVIDIA.WordStyles    
                 style of 'bare-metal'                                
 99:9   warning  '-' should use title            NVIDIA.HeadingTitles 
                 caps-style capitalization.     

 content/cumulus-netq-40/Validate-Operations/_index.md
 120:328  warning  Possible future tense ??  NVIDIA.FutureTense 
...
✖ 1 error, 408 warnings and 0 suggestions in 131 files.
pete$

The Vale output breaks down as follows:

  • Name of and path to the file with the issue.
  • The location of the issue in the Markdown file. For example, 35:60 means line 35, cursor position 60.
  • The severity of the issue, which is one of error, warning or suggestion.
  • The error message itself.
  • The Vale configuration file that references the rule. For example, NVIDIA.WordStyles is the WordStyles.yml file in the utils/.vale/NVIDIA directory.

Ignore Errors

Occasionally, Vale may flag something as an error, when it is actually a false positive. If the word choice or spelling is a valid reason to violate the rules, you can disable the Vale check for that text. For example, the NVIDIA Vale style guide states that there should not be any punctuation in a title, but that does not work for version numbers, as in the following example:

## For Servers Running Ubuntu 16.04 or 18.04
 
Run the following command to view the NetQ Agent version.

Vale returns the following error when it checks that heading:

21:33  warning  '.' should use title            NVIDIA.HeadingTitles
                 caps-style capitalization.

To avoid the error, you can disable Vale for that heading in the source file. Wrap the whole paragraph in <!-- vale off --> and <!-- vale on --> tags:

<!-- vale off -->
## For Servers Running Ubuntu 16.04 or 18.04
<!-- vale on -->
Run the following command to view the NetQ Agent version.

The <!-- vale on --> tag must be on its own line in order to reenable Vale checking; otherwise, Vale ignores the rest of the file.

Vale currently has a bug where it does not properly ignore a hyphen (-) in a title. If you wrote a heading with a hyphen and see this error, disable Vale and add a comment so we can find it later. For example:

<!-- vale off -->
<!-- vale.ai Issue #253 -->
### Any-source Multicast Routing (ASM)
<!-- vale on -->

Expand the Checks

Feel free to suggest modifications for anything in the .vale folder, or submit your own pull request.

Troubleshooting Hugo

Large Changes

If Hugo is currently running and a large volume of changes are made, for example, changing branches, Hugo may not always detect the changes. Stop and restart Hugo to see the new changes.

Hugo pipe failed Error

When launching Hugo it may fail and produce a traceback similar to the following:

Start building sites …

                   |  EN
-------------------+-------
  Pages            | 1736
  Paginator pages  |    0
  Non-page files   | 6722
  Static files     | 1685
  Processed images |    0
  Aliases          |    0
  Sitemaps         |    1
  Cleaned          |    0

Built in 18957 ms
Watching for changes in /git/docs/{content,static,themes}
Watching for config changes in /git/docs/config.yml
fatal error: pipe failed
▼ Traceback Output

This is caused by operating system limits on the number of open files. The way to verify and adjust this depends on the operating system and version in use.

Mac OSX 10.4 Mojave and Later

To adjust the max file limits, you must change both the kernel settings and session ulimits.

sudo sysctl -w kern.maxfiles=65536
ulimit -n 65536 65536

The ulimit adjustment only lives for the life of that terminal window. If the window is closed or a new window is open, the ulimit command must be run again.

Sparse Checkout

It is possible to only check out a portion of the docs repository to work on only the section you wish to contribute to. Git refers to this partial checkout as a sparse checkout.

A sparse checkout speeds up Hugo build times, limits the amount of local disk space that is used and can be a valid workaround for the Hugo pipe failed error message.

To create a sparse checkout:

  1. Create the destination directory for the repo:

    mkdir docs

  2. Enter the new directory and initialize it with Git:

    cd docs
git init

  3. Add the docs repo as a Git Remote:

    git remote add -f origin git@github.com:CumulusNetworks/docs.git

  4. Configure this directory as a sparse checkout:

    git config core.sparseCheckout true

  5. Configure Git to check out the mandatory docs files:

    echo "utils/" >> .git/info/sparse-checkout
echo "config.toml" >> .git/info/sparse-checkout
echo "build_trigger.txt" >> .git/info/sparse-checkout
echo "themes/" >> .git/info/sparse-checkout
echo ".vale" >> .git/info/sparse-checkout
echo "config.yml" >> .git/info/sparse-checkout
echo "static/mibs" >> .git/info/sparse-checkout

  6. Add the content you wish to modify to the Git sparse checkout. This includes both the files in the /content directory as well as any relevant images in /static/images directory. For example, to make contributions or modifications to Knowledge Base articles add both the /content/knowledge-base and /static/images/knowledge-base directories.

    echo "content/knowledge-base/` >> .git/info/sparse-checkout
echo "static/images/knowledge-base/` >> .git/info/sparse-checkout

  7. Checkout the appropriate branch:

    git checkout stage

  8. Adjust the Hugo configuration to ignore link checking.

    If you plan to run Hugo locally, due to how the Hugo ref shortcode validates links it will cause Hugo to fail at runtime due to the sparse checkout. The Hugo configuration must be changed locally to only log Warnings and allow Hugo to start

    echo "\nrefLinksErrorLevel: WARNING" >> config.yml

  9. Configure Git to ignore the config.yml file to prevent an accidental commit of this change:

    git update-index --assume-unchanged config.yml

  10. Run Hugo. You can safely ignore REF_NOT_FOUND warnings.

    hugo server --baseURL localhost:1313

All other git operations including git commit, git push and git checkout work normally.

    Copyright © 2024  NVIDIA Corporation