Add documentation site - #11
Open
leslieyip02 wants to merge 3 commits into
Open
Conversation
Consolidates documentation from 2 sources: 1. Markdown files in docs/ with MkDocs 2. Kotlin API docs with Dokka
Moved Dokka's module.md into a standalone dokka/ directory since the docs/ directory is used for MkDocs.
- Grouped markdown files into folders - Cleaned up command documentation - Update README
This file contains hidden or 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
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.
Currently, there are 2 sources of documentation:
docs/folder contains markdown files./gradlew dokkaHtmlcan be used to generate Kotlin API documentationThis PR combines both into a static site, which can be deployed via GitHub Pages.
Static Site Generation
I added MkDocs with Material for MkDocs to generate static HTML content from the markdown in the
docs/folder.The commands are all grouped together, and serving the site locally is as simple as:
# Assuming you have python3 installed somewhere ./scripts/build_docs.sh ./scripts/serve_docs.shThe end result looks like this:
The Kotlin API docs can also be accessed at
/api:Note: I moved the
docs/Module.mdfile used by Dokka intodokka/module.mdso thatdocs/is purely MkDocs content.I feel that having a static site improves the docs reading experience, and also allows more customization. For example, we can add notes, warnings, TODOs, and collapsible sections.
GitHub Actions
I've added a workflow to host the docs site on GitHub Pages. To set this up, go to Settings > Pages and set the "Build and deployment" source to GitHub Actions.
Since I don't have repo permissions, I created a fork to test the GitHub Actions as well: https://leslieyip02.github.io/jade/ (the content here is different, I just deployed it test the workflow).
Content Cleanups
I tried to clean up the docs as much as I can, and I grouped them as follows:
That said, there's a lot of confusing / outdated docs so I dumped everything I wasn't sure about into
archive.md.