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 website redesign #1909

Merged
merged 9 commits into from Nov 4, 2018

Conversation

Projects
1 participant
@ricardograca
Copy link
Member

ricardograca commented Nov 4, 2018

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-pages website with a master/docs based 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.

ricardograca added some commits Aug 12, 2018

Remove project changes notice from Readme
- Anyone interested should have had enough time to read it by now.
Update plugin doc
- This isn't being used right now, but it should be a first step towards 
having proper plugin documentation.
Remove link from project title
- 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.

@ricardograca ricardograca added the docs label Nov 4, 2018

@ricardograca ricardograca added this to To Do in Version 0.14.0 via automation Nov 4, 2018

@ricardograca ricardograca merged commit 5b5b7f9 into master Nov 4, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

Version 0.14.0 automation moved this from To Do to Done Nov 4, 2018

@ricardograca ricardograca deleted the rg-new-docs branch Nov 4, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment