Start on docs restructure

[palmtree5]

Description of the changes

Implements #2802. This is a WIP for now

[palmtree5]

From the mentioned issue, the idea is to have 4 main categories in the docs:

• Installation and Setup Docs (stuff done on the host system)
• User Docs (stuff done through Discord, @retke has done some great work here with [V3] User documentation #1757 and [Docs] Getting started guide #2659)
• Cog Developer Docs (stuff available for use by 3rd party devs)
• Red Developer Docs (what this issue is about)

The current structure of the sidebar is:

• Installation Guides
  • This includes things like installing/updating the bot, creating a bot account, venvs, and autorestart for various OSes
• Cog Reference
  • Currently has 3 pages under it: One for CustomCommands, one for Permissions, and one on Trivia list creation
• User Guides
  • Covers all the cog guides with command usage, the "getting started" guide, intents, and EUD
• Red Development Framework Reference
  • Catchall for Cog dev guides and API reference
• Changelogs

Basically, the target of this probably needs to be the Red Dev Framework Reference section and creating a section to document internals (but definitely note that stuff there is not covered by our guarantees). Do we break out the handful of cog creation guides from what is largely API reference? Do we rename the current Red Dev Framework Reference section? My thoughts on both of these questions is yes, we should. I think the target structure should be:

• Installation Guides
• Cog Reference
• User Guides
• Cog Creation Guides
• Cog Development Framework Reference
• Red Internal Docs (this could cover Red internals, but also things like the release process or anything else we feel necessary to document in terms of internal processes of how we do things)

Theoretically, the pages in Cog Reference could be merged into their respective user guides, but I can't remember right off hand if that was discussed previously and we had a reason for keeping them separate or if we just never discussed that.

[Kowlin]

While you're in there could you fix a major annoyance I have with the docs? and that's the MASSIVE list of changelogs, I think having the page is fine, but all the versions do not have to show up on the sidebar ToC.

[palmtree5]

While you're in there could you fix a major annoyance I have with the docs? and that's the MASSIVE list of changelogs, I think having the page is fine, but all the versions do not have to show up on the sidebar ToC.

This has been implemented now

[palmtree5]

Ok, 5 pages have been separated out to the Cog Creation Guides section, and Red Development Framework Reference has been renamed to Cog Development Framework Reference. Additionally, a section has been created for Red Developer Docs, however this does not show in the sidebar at this time due to being empty. I figure we can populate that with docs as we write them though, but that could easily be done over time as we decide them

[Jackenmen]

While you're in there could you fix a major annoyance I have with the docs? and that's the MASSIVE list of changelogs, I think having the page is fine, but all the versions do not have to show up on the sidebar ToC.

@Kowlin The list of all versions showing in the sidebar is unrelated to what's in docs/index.rst and has already been addressed in #5602 by adding the missing top-level header (which resulted in each release having it's own h1 header lol). The change made here to docs/index.rst only affects what's shown on the documentation's index page: https://docs.discord.red/en/latest/index.html

It may be fine to change maxdepth there but I just wanted to make sure that we're clear about what's being changed here. I'd also like to note that if we're changing maxdepth here, I think it would make sense to change it for some other sections as well. For example, maxdepth: 2 seems absolutely useless for most if not all documents in the "User guides" section and it expands the height of the table of contents A LOT.

[Jackenmen]

Additionally, a section has been created for Red Developer Docs, however this does not show in the sidebar at this time due to being empty. I figure we can populate that with docs as we write them though, but that could easily be done over time as we decide them

Do you have any specific details on what would be put here? In the past I've made some effort in a separate repository as it seemed to make some amount of sense to me to separate it from the main documentation: https://github.com/Jackenmen/Red-DevGuide/pulls I never pulled it into the org since I've never fully finished any of the documents. I've been using the release process document as a reference for a long while though so I should probably just get into the org... But either way, I'm not sure if the section you're proposing here is supposed to cover the same kind of things or if there's anything else that was supposed to be put there.

[palmtree5]

Going to reply to both comments in one here so bear with me

While you're in there could you fix a major annoyance I have with the docs? and that's the MASSIVE list of changelogs, I think having the page is fine, but all the versions do not have to show up on the sidebar ToC.

@Kowlin The list of all versions showing in the sidebar is unrelated to what's in docs/index.rst and has already been addressed in #5602 by adding the missing top-level header (which resulted in each release having it's own h1 header lol). The change made here to docs/index.rst only affects what's shown on the documentation's index page: https://docs.discord.red/en/latest/index.html

It may be fine to change maxdepth there but I just wanted to make sure that we're clear about what's being changed here. I'd also like to note that if we're changing maxdepth here, I think it would make sense to change it for some other sections as well. For example, maxdepth: 2 seems absolutely useless for most if not all documents in the "User guides" section and it expands the height of the table of contents A LOT.

Yeah, I think maxdepth: 2 on the user guides section kinda just expands it out a lot. I think it should stay for the "Cog Development Framework Reference" (although it IS a bit inconsistent IMO in terms of what is shown on the index page (i.e. in some spots you have a direct clickable link to take you right to a specific function, in other cases, you have to open the page and scroll through to find what you are looking for or click multiple things on the sidebar to show the list of functions in a "API Reference" section), see this screenshot below)

It almost could be worth the "Cog Development Framework Reference" having its own index page such that we could potentially go with something not deep for the main index page, but then have something deep for that section's specific index so that there could be a quick way to navigate to exactly what you are looking for.

Additionally, a section has been created for Red Developer Docs, however this does not show in the sidebar at this time due to being empty. I figure we can populate that with docs as we write them though, but that could easily be done over time as we decide them

Do you have any specific details on what would be put here? In the past I've made some effort in a separate repository as it seemed to make some amount of sense to me to separate it from the main documentation: https://github.com/Jackenmen/Red-DevGuide/pulls I never pulled it into the org since I've never fully finished any of the documents. I've been using the release process document as a reference for a long while though so I should probably just get into the org... But either way, I'm not sure if the section you're proposing here is supposed to cover the same kind of things or if there's anything else that was supposed to be put there.

That's actually exactly the sort of thing I'm talking about adding in that section

[Jackenmen]

That's actually exactly the sort of thing I'm talking about adding in that section

In that case, I think we'll have to discuss whether we want to keep contributor documentation on a site that so far has focused on documentation for users (supported methods of installation) and cog creators (supported APIs), not documentation that could be widely considered unsupported for end-user support or version-covered APIs such as potential documentation of internals (now I saw that you mentioned in an earlier comment), setting up dev environment (unsupported install from Git), and in general, things that don't concern the typical readers of our documentation (release process, issue triaging, other meta stuff).

[palmtree5]

That's actually exactly the sort of thing I'm talking about adding in that section

In that case, I think we'll have to discuss whether we want to keep contributor documentation on a site that so far has focused on documentation for users (supported methods of installation) and cog creators (supported APIs), not documentation that could be widely considered unsupported for end-user support or version-covered APIs such as potential documentation of internals (now I saw that you mentioned in an earlier comment), setting up dev environment (unsupported install from Git), and in general, things that don't concern the typical readers of our documentation (release process, issue triaging, other meta stuff).

I think if we did include this in the main docs, what that could look like would be a single page under the category on the main index page, then a subpage with its own toctree for all of that.

So something like creating a folder called dev, then a file in that folder called index.rst which would contain a toctree for the pages to be included there. This index page gets linked to in the Red Developer Docs section of the main index, with :maxdepth: 1, then the dev index specifies :maxdepth: 2

The other option for those docs would be in an entirely separate repo and thus an entirely separate site