Docs Rework

[Notenlish]

Docs Rework

Pygame-ce documentation is old and has a bunch of legacy stuff and different formattings. This issue is meant to be a tracker to rewrite pygame-ce docs and have discussion about it.

General Issues

Old and outdated documentation styling. This PR aims to fix it: #2924
Inconsistent Docs formatting: #3130
Tutorials and convention : #1924

Suggestions

Adding User Guide

I believe we should replicate what https://docs.pola.rs/ has done, with the documentation being split into User Guide, API Reference and Development. That way we'll be able to accommodate both beginners, advanced users as well as contributors to pygame-ce.

Proper Code Structure

There are many old pygame tutorials available on the web, and this results in really poor code quality by newcomers. Not to mention that this also leads to a lot of issues when pygame-ce users use Pygbag to export their games. I believe a proper page for "pygame-ce approved" project structure is needed.

Performance Improvement

A lot of newcomers struggle with getting good performance while using pygame, there are common issues such as loading the same images every frame and drawing a lot of things using regular python loops. A dedicated performance page is a must in my opinion.

Pygame on Web

There should be more resources on how to avoid common issues and problems with pygbag. The majority of these should be in pygbag, however I believe it would make sense to at least include a special page/module in the docs for putting pygame games on the web.

Dedicated page for Blending Modes

There should be a dedicated documentation page or an interactive page in Pygame Community Website

Getting Rid of Obsolete Information

The current pygame docs has some old stuff from pygame 1.x. Stuff like New in pygame 1.9.5. could be removed. If we want to keep these information, we can store different versions of the wiki

Keeping Multiple Versions Of The Wiki

Self explanatory.

[Notenlish]

Bot Integration

We can add special commands to help solve common issues that beginners have or provide info. A command to automatically show documentation for a module/function could be helpful, related to Pygame Community Bot

[bilhox]

I personally agree with all what was said above, so this is my plan :

• Add the new theme, only accessible in local for now
• Bring an homogeneous style for all pages
• Split and refactor parts of the docs
• Add new pages for user guide, pygbag ...
• ESPECIALLY for the new version : add access to pygame C API docs
• Sort docs pages so it's well intuitive and accessible for users (doctree)
• Deploy the new version according to how it was discussed with other members

Please to keep this issue clean, join us on discord in the website thread in the channel contributing.

[Notenlish]

Please to keep this issue clean, join us on discord in the website thread in the channel contributing.

Here's the website thread in case people cannot find it: https://discord.com/channels/772505616680878080/1114570952777420861

[Notenlish]

Improvements Compared To Pygame

This could be a single page or multiple pages, depending on how many features were added since the fork.

Improvements would be seperated like so:

• New Modules, functions, arguments to functions
• Performance Improvements(could be put in a different page, there should be another bug tracker for things to list in the performance additions page)
• Bugfixes

These don't necessarily need to be in the documentation, we can put it to the pygame.community site too.

[aatle]

About user guides

Improving the pygame beginner experience.

Current issues

Currently, a new pygame user usually starts with a YouTube tutorial.
There's a risk of the tutorial not being suitable, often leading to copy-pasting code -> tutorial hell.

There are old tutorials at https://pyga.me/docs/#tutorials, but hardly anyone uses them.

Goals

A new user should quickly learn the essential topics and concepts of pygame games.
This is so that they know about the various topics they need to learn about, and don't feel lost on what to do.
Then, there should be resources available for topics the user needs to learn for their game, e.g. physics. This could also help amateur and advanced users.

---

Introductory Guide

The introductory guide is a broad overview for beginners, pretty standard:

• Getting Started
  • What is pygame-ce?
  • Installation
  • Step by step game tutorial (explaining each feature/concept along the way)
    • Give full game code at the end
    • Challenges
  • Overview of features and concepts learned

User Guides

Perhaps there should be something like a pygame wikipedia, where a topic is explored in an article, possibly user-generated.
The benefits are that information is centralized and less likely to be outdated or bad quality.
There would be a directory to easily navigate and find specific topics:

Possible user guides

- Graphics
  - Blending modes
  - ...
- Input
  - Controller
  - ...
- Physics
  - ...
- Porting
  - Pygbag
  - Pyinstaller
- Performance
  - Profiling
  - Blitting
  - ...
- Common Systems
  - Animations
  - Tile maps
  - ...
- Contributing
  - Reporting bugs
  - ...
- Code Structure
  - Game loop
  - Sprites
  - ...
- ...

Achievable?
Articles will need to be written and contributed dynamically over time.
If it is written by the community, user-generated, then moderation and maintenance is needed.
If not, then only the important articles can be written.

Each article could be structured like a wikipedia article. They might be really short. They might reference tutorials and documentation, possibly containing only links to external information to save writing.

You can see that these guides will include many of the pages that have been suggested. This way, all of the information other than the introduction and API reference is unified.