Documentation website redesign #1909
Merged
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
- Anyone interested should have had enough time to read it by now.
- This isn't being used right now, but it should be a first step towards having proper plugin documentation.
- It's not needed as there are already lots of links to the website on the website itself, where it will be shown, and the readme file.
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.
Introduction
This implements some changes necessary to make the documentation look better with the new jsdoc theme that allows having multiple distinct sections in the website, notably the API Reference separated from the Guides.
Motivation
To provide a better experience for new developers and to help more experienced developers find the information they need. It also opens up the tutorials to further expansion and better organization.
Proposed solution
This separates the pure API Reference from the Tutorials (called Guides here) and the Home page. It should make it easier to find the wanted information without having to scroll a very long single page of information.
Also replaces the
gh-pageswebsite with amaster/docsbased one that is decoupled from releases for faster documentation roll-outs.Fixes #1507. Closes #1908.
Current PR Issues
The guides sections should be expanded in the future with a more detailed Getting Started section than what is available in the Readme file currently. For now it only makes use of the already available tutorials.
Alternatives considered
I experimented with a lot of third-party JSDoc themes before deciding to try to modify the existing one since, all of the other ones that fit the bill in terms of having different sections, had some flaws or lacked some features.