Documentation Update

[cmsirbu]

What's changed

• Moved existing documentation into a new structure to prepare for the mkdocs rendered docsite.
• Edited and improved the visuals in various places using new syntax from the Material for Mkdocs theme.
• Added dependencies to poetry environment for development.
• Added configuration for building and hosting the docsite on RTD.
• Replaced the project README with a standardized one. Note: the README will have certain links/images broken until the PR is merged into develop.
• Added invoke docs task to aid serving docs locally in the dev environment.
• Added test to check that RTD used docs/requirements.txt are in sync with dependencies in pyproject.toml.

Building docs

You can build the docs locally in the poetry environment:

poetry install
poetry run mkdocs serve

See below notes on development environment (more specifically the docker based one).

TODO

Some sections throughout the files listed below require input (or removal if not applicable to this plugin). All Developer Note comments should be resolved and removed.

• user/app_overview.md
• user/app_use_cases.md
• user/app_getting_started.md
• user/faq.md
• user/external_interactions.md
• admin/install.md - review
• admin/upgrade.md
• admin/uninstall.md
• admin/compatiblity_matrix.md
• admin/release_notes - I think the CHANGELOG content should be linking to the docs section release notes (and its contents moved into docs/admin/release_notes, but will leave this decision up to you.
• dev/extending.md - review
• dev/contributing.md
• dev/dev_environment.md - boilerplate guide based on cookie template (old GETTING_STARTED guide). A sync to the cookie dev environment would be beneficial to ensure instructions are accurate.
• dev/code_reference - check examples provided and add any module/package auto-generated docs that are relevant
• README.md - add description/overview

[glennmatthews]

The implication here is that we don't support any Nautobot version after 1.3.7?? Normally I'd expect the last supported version to be 1.5.99 (i.e. any 1.x version, but not 2.x).

[chadell]

Yes, this is the goal, but testing Nautobot 1.4.x and 1.5.x is not working (issue open), so I tried to keep it as close to reality as possible (until we solve how to support them)

[glennmatthews]

Do we have a team/codeowners alias that we can identify here instead of making me solely responsible? :-)

[chadell]

could we use the github team @nautobot/po-tl-data-management?

[glennmatthews]

Removal of file checksums here and below suggests that you are running an older version of poetry and/or need to run poetry cache clear pypi --all, then regenerate the file with poetry lock --no-upgrade.

[cmsirbu]

Hopefully fixed, I was using poetry 1.1.13 - updated to 1.3 now.

[cmsirbu]

@chadell a few fixes to resolve build warnings and formatting.

[cmsirbu]

@chadell @glennmatthews You can't tell from the PR itself, but I retriggered the CI to run and it's actually succeeding now -> https://github.com/nautobot/nautobot-plugin-netbox-importer/actions/runs/3696298530

[glennmatthews]

Looks like this repo isn't enabled for ReadTheDocs yet? At least I don't see any RTD steps in the CI results.

[cmsirbu]

@glennmatthews it's all set up on RTD - they use their own CI with webhooks from here: https://docs.nautobot.com/projects/netbox-importer/en/latest/

It's currently building from this branch, so the landing page is a bit broken until this gets merged to develop.

[chadell]

LGTM