Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Updates #184

Closed
wants to merge 1 commit into from
Closed

Documentation Updates #184

wants to merge 1 commit into from

Conversation

cmsirbu
Copy link

@cmsirbu cmsirbu commented Nov 14, 2022

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 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.

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
  • 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/design.md - migrated file with edits and formatting, to be reviewed
  • dev/code_reference - check examples provided and add any module/package auto-generated docs that are relevant
  • dev/arch_decision.md
  • README.md

Other issues:

  • Couldn't add docs dependencies (see docs/requirements.txt for exact versions) to poetry environment for development because of Python 3.6 and Jinja2 conflict with Nautobot 1.2.
And because nautobot (1.2.11) depends on Jinja2 (>=2.11.3,<2.12.0)
   and mkdocs-material (8.4.2) depends on jinja2 (>=3.0.2), mkdocs-material (8.4.2) is incompatible with nautobot (>=1.2.1,<1.3.0).

For reference this is what should be added:

poetry add --dev mkdocs="1.3.1"
poetry add --dev mkdocs-material="8.4.2"
poetry add --dev mkdocs-version-annotations="1.0.0"
poetry add --dev mkdocstrings="0.19"
poetry add --dev mkdocstrings-python="0.7.1"

@bryanculver
Copy link
Member

Build blocked by #185

@bryanculver bryanculver added the status: blocked Another issue or external requirement is preventing implementation label Mar 8, 2023
@itdependsnetworks
Copy link
Contributor

Replaced with af87798

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
status: blocked Another issue or external requirement is preventing implementation
Projects
No open projects
Development

Successfully merging this pull request may close these issues.

3 participants