Cog-Creators / Cog-Creators/Red-DiscordBot

[Docs] Restructuring Documentation and Re-classifying public APIs

Open
#2,802 6 comments 0 reactions 1 assignee Claimed by @palmtree5 View on GitHub
Category: Docs - Other Status: Accepted Type: Enhancement
Dominant language
Python
Stars
5.7k
Forks
2.5k
Avg merge
6d 16h
Merged PRs (30d)
1

Description

Some stuff on our public developer documentation, which is aimed at cog creators, should really only be documented for internal use and subsequent to changes at any time. This is following on from a bit of a rant of mine over in #2774.

### What should be moved?
As I mentioned there, with respect to APIs which are already documented, candidates for moving to these internal docs would be:
- The Downloader API and cog reference
- The drivers API reference
- The cog manager API reference
- A bit of the data manager API reference (creating instances, storage details and all that)
- Things like `cog_data_path()` should obviously remain public
- Things like `load_basic_configuration()` should be documented internally but we should reconsider how our testing framework handles stuff like this.

Obviously there are lots of things we could *add* to these docs, which don't already exist in the public docs but would be useful in these internal docs. But I'm not setting any milestones for adding that stuff right now, because it can be quite a lot of work.

### Where should these internal docs be located?
On the same RTD site is fine, just under a new section. The sections are currently a bit muddled up - I think we need to redefine them as four clear sections:
- Installation and Setup Docs (stuff done on the host system)
- User Docs (stuff done through Discord, @retke has done some great work here with #1757 and #2659)
- Cog Developer Docs (stuff available for use by 3rd party devs)
- Red Developer Docs (what this issue is about)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.