[POC] Developer Documentation Revamp using mkdocs #14179
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…layout yet though Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
Signed-off-by: Rick Elrod <rick@elrod.me>
AlanCoding
reviewed
Jul 5, 2023
| run: | | ||
| mkdocs build --clean | ||
|
|
||
| # TODO: Deploy the site somewhere (gh pages?) |
There was a problem hiding this comment.
Reading up on the limitations of this... github pages seem to want an index.html at the root level. Since this would be an artifact of the build process, we probably don't want to keep that in source ourselves. Then the URL would be somewhat limited, as we could have maybe http://ansible.github.io/awx, which would maybe be okay, maybe not.
Given what other projects are doing...
- https://ansible.readthedocs.io/projects/builder/en/stable/
- https://ansible.readthedocs.io/projects/runner/en/stable/
I would just assume we go with readthedocs.io
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
SUMMARY
I started on this a few months ago, and dusted it off and did some more work on it tonight.
Just a proof of concept for what would dev docs could look like using mkdocs.
I moved the docs files around to roughly organize them, but I am not happy with the organization yet.
mkdocs-material (the theme I am using here) has a "tags" feature which helps to group documents together, and I think this is more useful than the directory structure. But the directory structure determines the hierarchy of the navbar on the left of the site.
Front page 📄
Tags index 🏷️
Search 🔍
Built-in Mermaid graphs(!) 📈
ISSUE TYPE
COMPONENT NAME