Introduce new website with docs with docusaurus

[KyrietS]

Website with docs for Premake 4.x and 5.0

This idea is discussed in #1547

Structure

Whole website is stored in folder website (followed convention from Docusaurus wiki). Docs for Premake 5.0 are stored in markdown files in website/docs. Some minimal changes have to be done for files downloaded from current github-wiki docs.

I've added many examples in this commit so it's easy to understand everything (I hope).

Example is temporarily hosted on my repo: https://kyriets.github.io/premake-core/

Building website

read website/README.md

tl;dr
(Node.js with npm needed)

cd website
npm install
npm start             # development
npm run-script build  # build static files

Building website with GitHub Actions

Example here

Migration / editor notes

• Lua syntax highlight is supported (```lua).
• Shell code blocks can (should?) be marked with ```bash.
• You can highlight a line in a code block, eg. ```lua {3}.
• We should change every occurrence of **inlineCode()** to `inlineCode()`.
• In general, sometimes **bold text** is overused. In many places `inline mono` should be used instead.
• Markdown files can have front matter (config fields, markdown headers). Here are all supported fields: https://v2.docusaurus.io/docs/markdown-features#markdown-headers, but...
• It's better NOT to use front matter if it's possible. It'll be easier to maintain for everyone. You just have to remember that id: defaults to filename and title: defaults to id if not provided. So instead of creating front matter in file os.mkdir.md like this:

---
id: os.mkdir
title: os.mkdir
---

it's better not to provide front matter at all. (id is used to create link in sidebar)

• Unfortunately sidebar items are not sorted. So it might be a pain if we wanted to keep them in alphabetical order like in GH wiki ;C
• Instant search support can be added after the website is published (tutorial) and it looks nice IMO.
• All assets (like images) must be placed in website/static folder so they can be referenced with global path, eg. we have an image in /website/assets/img/image.png and if you want to include this image in docs page you should write: ![alt text](/img/image.png). There is no /assets/ before image path! It'll be added by Docusaurus automatically.
• When linking to another document use relative path with *.md extension. Docusaurus will generate valid urls and links will also work when browsing on GitHub. Additionally, you will get a warning message when link to a markdown file can't be resolved. (there are many warnings like this at this moment).
• There is a special page: /website/docs/Style-Guide.md that showcases all markdown features in Docusaurus. This page is not listed in sidebar. It's quite useful, especially when you modify theme and styles.
• In general, migrating docs is super easy.
• At this moment docs pages with os prefix (os.mkdir, os.rmdir, etc.) are grouped in sidebar. I'm not sure if we want this.
• Page /website/src/pages/download.md is work-in-proggress. It's also an exmaple of how you can add another page to the website.

[starkos]

Looks absolutely fantastic, you've done a great job with this.

Curious: why are 4.x docs are under versioned_docs but 5.x docs are just docs? If I start bring docs for the next version online where would they go? Would it make sense to keep all reference material under versioned_docs?

I do prefer having each library (os, path, etc.) broken out into its own group in the sidebar. I think we should keep them in alpha order so I guess that's just something we'll have to figure out and maintain manually. Not a showstopper.

Here's a question…at some point we may need to track development of a v5.x and a v6.x. Those would probably maybe be on separate branches, and would stay on separate branches so we could keep maintaining v5? Not sure how we would track the documentation in that setup. Maybe we just publish from the latest (v6) branch? Something that we might need to address but I don't see any reason to let it hold this up.

Again, great work with this! I'd like to get feedback from @samsinsane but atm I see no reason not to land this and start redirecting the wiki pages over to here. Are you cool with landing this PR as is and then iterating on the content, or are you intending to do more work on it first?

[KyrietS]

Thanks for your feedback! I really appreciate it.

Curious: why are 4.x docs are under versioned_docs but 5.x docs are just docs? If I start bring docs for the next version online where would they go? Would it make sense to keep all reference material under versioned_docs?

It's all about URLs. Docs in docs are meant for the latest/current (or even next) version of Premake. It gives us URLs with custom paths like this: /docs/os.chdir (atm path is empty "", by default it's "latest" or "next". See 102 line of docusaurus.config.js). If all docs were placed under versioned_docs then there would be no /docs/os.chdir. Instead, we would have: /docs/5.x/os.chdir so only versioned URLs. When development of 6.x is started, 4 things will be done:

1. all docs will be copied into versioned_docs/version-5.x/
2. sidebar.js will be saved to versioned_sidebars/version-5.x-sidebars.json
3. new version "5.x" will be added to versions.json
4. finally, you would have to manually update "current version label" to "6.x" in docusaurus.config.js.

And from this moment link docs/os.chdir would reference 6.x version of os.chdir. Old one would be docs/5.x/os.chdir. As you can see, it's all about URLs. This approach is mentioned in Recommended practices of Docusaurus. Think of versioned_docs as historical snapshots of docs.

Here's a question…at some point we may need to track development of a v5.x and a v6.x. Those would probably maybe be on separate branches, and would stay on separate branches so we could keep maintaining v5?

In general, website should have only one version (the published one). If we started development of a 6.x on a separate branch then docs would need to be maintained on master in order for them to be published. It's still possible to maintain 6.x docs on a branch and merge webite into master later.

Are you cool with landing this PR as is and then iterating on the content, or are you intending to do more work on it first?

Yes, this PR is intended to be merged so other people can be involved in docs migration :-)

[starkos]

Playing around with this some more…

• I'd like to remove all of the 4.x stuff from this site. We'll serve just the current documentation, and sort things out for the next version when we know more. Most likely we'll still just serve a single version of the docs with version specific notes inline, rather than try to maintain two separate collections. I appreciate you putting it together so I could see how it works though; looks straightforward.

• At some point, sooner than later, we'll need info on deployments in the README: how it's done, when it's done, how to get to the relevant action, that sort of stuff. Understand if it needs to be deployed first.

Would it be possible for you to clean up the 4.x stuff? In the meantime I'll ping @samsinsane; if he has no objections I'd like to get this landed this week, and then I'll go head down on migrating the docs and see if I can't crank through it. I'd prefer not to go live until we have the majority of the content moved over, and I'd like to get this live ASAP.

[starkos]

Oh yeah…the website is served from a different repository—I assume we can set up the deployment action to push the results there?

[KyrietS]

I'd like to remove all of the 4.x stuff from this site.

Sure thing. But you said "try to maintain two separate collections". Actually the idea of versioned docs is that we maintain only one (current/latest/next) version of docs. Old historical API shouldn't be modified (at least not often, in theory ofc). I understand your point of view. Sections "Availability" look nice IMO but what about people using Premake4 who want to find functions for their version only?

Would it be possible for you to clean up the 4.x stuff?

Yes, I'll do it as soon as I can. Just clarify for me one thing. What should be left on the website: docs for 5.0 or just simply "docs" without version specified?

I assume we can set up the deployment action to push the results there?

Yes exactly. We will use GitHub Action in this repo to build static files and then automatically push them to the other repo. It's simple configuration, I've done it a few times already.

[starkos]

what about people using Premake4 who want to find functions for their version only?

v4 has its own repository and wiki. I'd prefer to focus on getting v5 ported over and cleaned up ASAP, so I can get back to everything else. If someone else feels like migrating the v4 docs after the fact I'm not opposed to it, but it doesn't seem necessary.

What should be left on the website: docs for 5.0 or just simply "docs" without version specified?

Let's go with just "docs" for now. Once I have a better idea of where the in-development code is going to land I can make changes if needed, but I don't expect it will be necessary.

Thanks again for taking the lead on this.

[slorber]

hey, please add this to our showcase :)

https://v2.docusaurus.io/showcase

[KyrietS]

hey, please add this to our showcase :)

when it's ready, sure :-)

Ok, I removed all 4.x stuff. There is only one version of docs on the website.
Live demo: https://kyriets.github.io/premake-core/ (use Shift + F5 to discard browser cache if needed)

[samsinsane]

Sorry I haven't looked at this sooner, it looks good to me.

[starkos]

Okay, I think we're good to go then. @KyrietS do you agree?

[KyrietS]

Yes. Merge it and let the migration begin 👍

[starkos]

Done. If you (or anyone) is planning to migrate documentation, let's coordinate over on #1547.