Skip to content
This repository was archived by the owner on Jan 29, 2021. It is now read-only.

[Prototype] Docs with Docusaurus #1111

Open
wants to merge 18 commits into
base: master
Choose a base branch
from
Open

Conversation

weerd
Copy link
Contributor

@weerd weerd commented Aug 23, 2020

What's this PR do?

This pull request is a prototype for a new documentation system we could use on some of our projects utilizing Docusaurus.

How should this be reviewed?

Casual 👀 just to see how it's implemented 😄

Any background context you want to provide?

This is a prototype demo for upcoming RFC.

@weerd weerd requested a review from a team as a code owner August 23, 2020 20:15
@weerd weerd requested review from mendelB and removed request for a team August 23, 2020 20:15
@dosomething-machines dosomething-machines had a problem deploying to dosomething-rogue-dev-pr-1111 August 23, 2020 22:03 Failure
@dosomething-machines dosomething-machines had a problem deploying to dosomething-rogue-dev-pr-1111 August 23, 2020 23:33 Failure
@dosomething-machines dosomething-machines temporarily deployed to dosomething-rogue-dev-pr-1111 August 23, 2020 23:45 Inactive
@weerd
Copy link
Contributor Author

weerd commented Aug 24, 2020

Notes

I had to create a number of scripts (not the best, can probably be cleaned up and/or improved if we go with this solution), since Docusaurus has its own package.json with scripts it uses to build/serve the docs. I was also attempting to get the docs hosted by the domain within the public/ directory and made it work, but there's probably a better way to handle that... 🤔

Anyhoo, to test locally while developing the docs, you can run:

$ npm run start:docs

And head to view the docs locally at: http://localhost:3000/build/. This links to the "landing page" for Docusaurus and the docs are at /docs. Docusaurus supports having a blog (/blog) and other static pages (we can remove these if desired), thus the docs are a subdirectory.

To try a build of the docs within the Rogue test domain, run:

$ npm run docs:dev

Then head to view the docs locally at: http://rogue.test/build/docs/.

Interesting note, when running a build, Docusaurus can check if the markdown files have any broken links and will throw errors if it finds any which seems super useful!

The npm run docs command I added is used by Circle CI and Heroku which is a bit more streamlined since it doesn't have to clean out any prior builds of the docs in /public/build.


A couple troubleshooting notes, of issues I encountered...

I had to increase the version of Node in our package.json since Docusaurus needs at least v10.15.

I also had an issue with Nginx on the Heroku Review Apps for the rendered docs and requires specifying /index.html at the end of the URL. I looked into it briefly and it may have something to do with the index page needing to be a .php file, but I didn't dig too deep since not really the point of this, and I was tired 😴

@mendelB mendelB removed their request for review October 16, 2020 13:47
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants