Nautobot Apps - Lab 10: Hosting App Documentation in Nautobot¶

For this lab, we'll learn how Nautobot can host documentation for custom built apps within its ecosystem. We will be utilizing the docs button found on the Installed Apps page on Nautobot.

Screenshot: Greyed Out Docs Button

At the end of this lab, you will be able to click the above button and be taken to documentation for your plugin.

Nautobot Apps - Lab 10: Hosting App Documentation in Nautobot
Task 1: Prep Environment for Plugin Documentaton
Task 2: Build Documentation
Task 3: Update Maintenance Plugin files
- Step 3-1 - Update urls.py
- Step 3-2 - Update __init__.py with docs_view_name
Task 4: View plugin documentation
- Step 4-1 - Restart your Nautobot Development Server
- Step 4-2 - View documentation fron Nautobot Installed Apps page
Task 5: Create Maintenance Notice model documentation
Task 6: View model documentation

Task 1: Prep Environment for Plugin Documentaton¶

Step 1-0 - Prepare for the Lab¶

For this and all remaining labs, it is advisable to open two terminal windows, one for running the Nautobot development server, and another for executing various commands.

The steps in this lab require that you have a terminal open and have switched to the nautobot user. Verify your username with the whoami command and switch user to nautobot if needed.

ntc@nautobot:~$ whoami
ntc
ntc@nautobot:~$ sudo -iu nautobot
nautobot@nautobot:~$ whoami
nautobot
nautobot@nautobot:~$

If you have the Nautobot development server running from a previous lab, please continue to the next step. Otherwise we need to start the server with the command nautobot-server runserver 0.0.0.0:8080 --insecure.

nautobot@ntc-nautobot-apps:~$ nautobot-server runserver 0.0.0.0:8080 --insecure
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
April 24, 2022 - 05:19:10
Django version 3.1.14, using settings 'nautobot_config'
Starting development server at http://0.0.0.0:8080/
Quit the server with CONTROL-C.

Step 1-1 - Create Docs Folder¶

In order for Nautobot to host our documentation, we need a place to store our files. Create a docs folder under the /opt/nautobot/plugin folder.

ntc@nautobot:~$ mkdir /opt/nautobot/plugin/docs

Step 1-2 - Download boilerplate `mkdocs.yml` file¶

We will be utilizing MkDocs for our plugin documentation. MkDocs can be heavily customized. Rather than doing all of the customization from scratch, we will download the MkDocs configuration file we use in our Example Plugin found in the core Nautobot GitHub repository. Much like the .gitignore we will use wget to retrieve the file. Run the following commands to download the needed mkdocs.yml file to the appropriate location.

nautobot@nautobot-1:~$ wget -O /opt/nautobot/plugin/mkdocs.yml https://raw.githubusercontent.com/nautobot/nautobot/develop/examples/example_plugin/mkdocs.yml
--2023-03-15 22:58:48--  https://raw.githubusercontent.com/nautobot/nautobot/develop/examples/example_plugin/mkdocs.yml
Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 185.199.111.133, 185.199.110.133, 185.199.108.133, ...
Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|185.199.111.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 2047 (2.0K) [text/plain]
Saving to: ‘opt/nautobot/plugin/mkdocs.yml’

opt/nautobot/plugin/mkdocs.yml                           100%[================================================================================================>]   2.00K  --.-KB/s    in 0s

2023-03-15 22:58:49 (9.48 MB/s) - ‘opt/nautobot/plugin/mkdocs.yml’ saved [2047/2047]

Step 1-3 - Update `mkdocs.yml` file¶

Because we took this from the Example Plugin, we need to update some values to match out maintenance-notices plugin. Update the first 5 lines to the values below.

---
dev_addr: "127.0.0.1:8001"
site_dir: "maintenance_notices/static/maintenance_notices/docs"
site_name: "Maintenance Notice Plugin Documentation"
copyright: "Copyright &copy; The Authors"

The rest of the file can be left as is.

Step 1-4 - Create `assets` folder¶

The Example Plugin mkdocs.yml file that we downloaded references a custom css file. Let's create the assets/overrides/partials folder path under our docs directory to hold that file.

nautobot@nautobot-1:~$ mkdir -p /opt/nautobot/plugin/docs/assets/overrides/partials

Step 1-5 - Download override file¶

nautobot@nautobot-1:~$ wget -O /opt/nautobot/plugin/docs/assets/overrides/partials/copyright.html https://raw.githubusercontent.com/nautobot/nautobot/develop/examples/example_plugin/docs/assets/overrides/partials/copyright.html

Step 1-6 - Download image files¶

The example plugin also references some images in the mkdocs.yml file. Download those to the directory created above.

nautobot@nautobot-1:~$ wget -O /opt/nautobot/plugin/docs/assets/nautobot_logo.svg https://raw.githubusercontent.com/nautobot/nautobot/develop/examples/example_plugin/docs/assets/nautobot_logo.svg

nautobot@nautobot-1:~$ wget -O /opt/nautobot/plugin/docs/assets/networktocode_bw.png https://raw.githubusercontent.com/nautobot/nautobot/develop/examples/example_plugin/docs/assets/networktocode_bw.png

nautobot@nautobot-1:~$ wget -O /opt/nautobot/plugin/docs/assets/extra.css https://raw.githubusercontent.com/nautobot/nautobot/develop/examples/example_plugin/docs/assets/extra.css

Step 1-7 - Create a requirements.txt file for our needed documentation packages¶

Create a doc_requirements.txt file with needed packages using the following command. These are packages required to build our plugin documentation.

nautobot@nautobot-1:~$ echo "mkdocs==1.3.1
mkdocs-material==8.4.2
mkdocstrings==0.19
mkdocstrings-python==0.7.1
Jinja2
mkdocs-include-markdown-plugin==3.6.1" >> /opt/nautobot/plugin/docs/doc_requirements.txt

Step 1-8 - Install `doc_requirements.txt`¶

Install doc_requirements.txt using the below command.

nautobot@nautobot-1:~$ pip install -r /opt/nautobot/plugin/docs/doc_requirements.txt

Task 2: Build Documentation¶

Step 2-1 - Create an `index.md` file¶

Create an index.md file in the docs folder and add a basic header with the name of the plugin.

nautobot@nautobot-1:~$ touch /opt/nautobot/plugin/docs/index.md
nautobot@nautobot-1:~$ echo "# Maintenance Plugin" >> /opt/nautobot/plugin/docs/index.md

Step 2-2 - Generate docs using mkdocs command¶

Now we will run the mkdocs build command. This command takes the mkdocs.yml configuration and the files under the docs folder to build documentation for our plugin. When running this command, we must be in the /opt/nautobot/plugin directory.

nautobot@nautobot-1:~$ cd /opt/nautobot/plugin/
nautobot@nautobot-1:~/plugin$ mkdocs build --no-directory-urls --strict
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs
INFO     -  Documentation built in 0.43 seconds

Note: This path displayed in the 2nd "INFO" message comes directly from the onfiguration changes we did in Steps 1-3

Step 2-3 - Verify created documentation¶

To verify the documentation was built successfully, let's look at the files within the /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs folder.

nautobot@nautobot-1:~/plugin$ ls -l /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs/
total 60
-rw-rw-r-- 1 nautobot nautobot 19070 Mar 16 15:35 404.html
drwxrwxr-x 6 nautobot nautobot  4096 Mar 16 15:35 assets
-rw-rw-r-- 1 nautobot nautobot   135 Mar 16 15:35 doc_requirements.txt
-rw-rw-r-- 1 nautobot nautobot 19557 Mar 16 15:35 index.html
drwxrwxr-x 2 nautobot nautobot  4096 Mar 16 15:35 search
-rw-rw-r-- 1 nautobot nautobot   234 Mar 16 15:35 sitemap.xml
-rw-rw-r-- 1 nautobot nautobot   190 Mar 16 15:35 sitemap.xml.gz

Awesome! mkdocs built a number of files for us based on our mkdocs.yml configuration file.

Task 3: Update Maintenance Plugin files¶

Now that docs are built, we still need to make a few changes in our plugin to view the docs.

Step 3-1 - Update `urls.py`¶

We need to add a url path to our documentation. Update the urls.py with the below code..

from django.views.generic import RedirectView
from django.templatetags.static import static

urlpatterns = [
    ...,
    path('docs/', RedirectView.as_view(url=static("maintenance_notices/docs/index.html")), name='docs'),
    ...,
]

Let's go over this. First we are importing RedirectView. This just takes a path and converts it to a URL. We are also importing static. This tag is actually a function that is used to reference files within the static folder.

Step 3-2 - Update `init.py` with `docs_view_name`¶

In our __init__.py file, add the following line to the MaintenanceNoticesConfig class. Here is the full class configuration with the newly added line at the bottom.

docs_view_name = "plugins:maintenance_notices:docs"

"""Plugin declaration for MaintenanceNoticesConfig."""

from nautobot.extras.plugins import PluginConfig

try:
    from importlib import metadata
except ImportError:
    # Python version < 3.8
    import importlib_metadata as metadata

__version__ = metadata.version(__name__)


class MaintenanceNoticesConfig(PluginConfig):
    """Plugin configuration for the maintenance_notices plugin."""

    name = "maintenance_notices"
    verbose_name = "Maintenance Notices"
    version = __version__
    author = "Student Name"
    description = "Nautobot plugin to manage maintenance notices"
    base_url = "maintenance_notices"
    required_settings = []
    min_version = "1.1.0"
    max_version = "1.9999"
    default_settings = {}
    caching_config = {}
      version = __version__
    author = "Student Name"
    description = "Nautobot plugin to manage maintenance notices"
    docs_view_name = "plugins:maintenance_notices:docs"


config = MaintenanceNoticesConfig

Task 4: View plugin documentation¶

We should now be all setup to view the documentation through Nautobot!

Step 4-1 - Restart your Nautobot Development Server¶

Open the terminal where you have your development server running and hit <CTRL> C to stop the server. Then, issue the command to start the server.

Quit the server with CONTROL-C.

^C
nautobot@ntc-nautobot-apps:~$ nautobot-server runserver 0.0.0.0:8080 --insecure
Watching for file changes with StatReloader
Performing system checks...
...

Step 4-2 - View documentation fron Nautobot Installed Apps page¶

Once Nautobot is up and running head to the Plugins > Installed Pugins page. The blue docs button should now be clickable.

Screenshot: Clickable Docs Button

One clicked, you should get redirected to new page that looks like the below screenshot.

Screenshot - Maintenance Plugin Docs

Congratulations! You've added documentation for your plugin hosted within Nautobot.

Task 5: Create Maintenance Notice model documentation¶

One other documentation trick of Nautobot is the ability to link to a model's specific documentation if the generic.ObjectEditView is used in your views.py. Currently, if you go to add a Maintenance Notice via Plugins -> Maintenance Notices -> Green + the page looks like the screenshot below.

Screnshot - Maintenance Notice Add No Docs

By the end of this task, there will be a ? that is clicakble on the above page that will send us straight to the models documentation.

Step 5-1 - Add `models` folder to `docs` folder.¶

Create a new folder titled models that will host our documentation for our plugins models.

nautobot@nautobot-1:~$ mkdir /opt/nautobot/plugin/docs/models

Step 5-2 - Create `maintenancenotice.md` file.¶

Within that folder, create the maintenancenotice.md file which will be the source of the documentation for our model. The title of these markdown files correspond directly to the slug of the model class name. Since our class is MaintenanceNotice our file is titled maintenancenotice.md

nautobot@nautobot-1:~$ touch /opt/nautobot/plugin/docs/models/maintenancenotice.md

Add a header and some text to the markdown file.

nautobot@nautobot-1:~$ printf "# Maintenance Notice\nThis is the landing page for the Maintenance Notice model documentation.\n" >> /opt/nautobot/plugin/docs/models/mainten
ancenotice.md

Step 5-3 - Recreate docs using `mkdocs build` command¶

Since we have added some new material, recreate the docs using the commands below. When you run this command, ensure you are in the opt/nautobot/plugin directory.

nautobot@nautobot-1:~/plugin$ mkdocs build --no-directory-urls --strict
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory:
            /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs
INFO     -  The following pages exist in the docs directory, but are not included in the "nav"
            configuration:
              - models/maintenancenotice.md
INFO     -  Documentation built in 0.49 seconds

Step 5-4 - Verify correct files were created.¶

Our mkdocs build command should have created a models folder and a maintenancenotice.html file under the /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs folder. Verify that by running an ls -l in the /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs directory and the /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs/models directory.

nautobot@nautobot-1:~$ ls -l /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs
total 64
-rw-rw-r-- 1 nautobot nautobot 19070 Mar 17 20:39 404.html
drwxrwxr-x 6 nautobot nautobot  4096 Mar 17 20:39 assets
-rw-rw-r-- 1 nautobot nautobot   135 Mar 17 20:39 doc_requirements.txt
-rw-rw-r-- 1 nautobot nautobot 19557 Mar 17 20:39 index.html
drwxrwxr-x 2 nautobot nautobot  4096 Mar 17 20:39 models
drwxrwxr-x 2 nautobot nautobot  4096 Mar 17 20:39 search
-rw-rw-r-- 1 nautobot nautobot   359 Mar 17 20:39 sitemap.xml
-rw-rw-r-- 1 nautobot nautobot   195 Mar 17 20:39 sitemap.xml.gz

nautobot@nautobot-1:~$ ls -l /opt/nautobot/plugin/maintenance_notices/static/maintenance_notices/docs/models
total 20
-rw-rw-r-- 1 nautobot nautobot 19479 Mar 17 20:39 maintenancenotice.html

Task 6: View model documentation¶

We have everything created for our model documentation. Let's go and take a look.

Step 6-1 - Restart your Nautobot Development Server¶

Open the terminal where you have your development server running and hit <CTRL> C to stop the server. Then, issue the command to start the server.

Quit the server with CONTROL-C.

^C
nautobot@ntc-nautobot-apps:~$ nautobot-server runserver 0.0.0.0:8080 --insecure
Watching for file changes with StatReloader
Performing system checks...
...

Step 6-2 - Verify model documentation¶

Navigate to Plugins -> Maintenance Notices -> Green +. You should now see a blue circle with a "?" mark in it.

Screenshot - Maintenance Notice Add with docs

If you click the "?" you will get redirected to the basic markdown file we added as model documentation.

Screenshot - Maintenance Notice Model Docs

Step 6-3 - Commit Your Changes¶

Remember to commit your changes to git:

nautobot@nautobot:~$
nautobot@nautobot:plugin/maintenance_noices$ git add -A
nautobot@nautobot:plugin/maintenance_notices$ git commit -m "Completed Lab 10."

This lab is now complete. Check your work against the solution guide before proceeding with the next lab.