New website style + docs sorting modifications #2924

bilhox · 2024-06-13T19:52:33Z

Hello,

This PR aims to change the website style after years of no modifications. I understand this is considered as a BIG UI change and there is a huge talk on the topic, so I want to make you understand the old theme isn't gone ! Indeed, the goal is to propose for the moment the new style only for static doc generation. Furthermore, the default style when generating docs is the old style, if you want to test the new website style, make sure to read docs/README.md, a small paragraph was added.

Any feedbacks would be considered as a great opportunity to progress on this idea ! I hope you like the new style.

damusss · 2024-06-14T08:26:34Z

src_c/doc/joystick_doc.h

@@ -1,25 +1,2 @@
 /* Auto generated file: with make_docs.py .  Docs go in docs/reST/ref/ . */
-#define DOC_JOYSTICK "Pygame module for interacting with joysticks, gamepads, and trackballs."
 #define DOC_JOYSTICK_INIT "init() -> None\nInitialize the joystick module."


Some failed checks are complaining about this, they can't compile the joystick module without this defined DOCs. I have no idea of how it works but I think some file or sphynx itself is reading the docs files and generating this entries. I am not sure why it's not finding them, have you run py setup.py docs --fullgeneration?

py setup.py docs --fullgeneration is deprecated as stated in docs/README.md. If I try to run it, I have an error with setuptools when it comes to call setup at the end of setup.py.

py setup.py docs --fullgeneration is deprecated as stated in docs/README.md. If I try to run it, I have an error with setuptools when it comes to call setup at the end of setup.py.

Weird, it works fine for me. Either way those #define need to come back, if you don't know how perhaps you should ask in #contributing (I don't know how either)

bilhox · 2024-06-16T08:18:27Z

After some reviews with Damus, we found that there is a problem a problem of opacity on links with a feature when you hover it, you get some kind of infos about it.
In the meantime, some parts of the documentation have been reworked as it doesn't follow the style of other docs pages.

Starbuck5 · 2024-06-16T23:00:31Z

In the meantime, some parts of the documentation have been reworked as it doesn't follow the style of other docs pages.

If you want to change content in the docs, do it in a separate PR. That doesn't belong in this PR.

oddbookworm

As Starbuck mentioned, content changes should be in a separate PR so that this one and those content changes are not both contingent on the other. I also have a few gripes here that I would like to see addressed (or explained if not addressable)

oddbookworm · 2024-06-30T15:04:38Z

docs/reST/ref/extra_infos/color_list.rst

@@ -1,4 +1,4 @@
-.. include:: common.txt
+.. include:: ../../common.txt


I don't know that I like the relative pathing here. Is there no way around it?

oddbookworm · 2024-06-30T15:07:01Z

docs/README.md

+You may want to test the new website style, you just have to edit
+``docs/reST/conf.py`` and change the value of ``html_theme`` to ``sphinx_book_theme``.
+(Make sure before to install the theme with ``python -m pip install sphinx_book_theme``)


Isn't this PR supposed to implement the new style? I'm confused by what's intended here

Hello, thank you for the review !

After a big talk on discord, a lot mentionned the idea of making a progressive transition between the old style and the new style. So right now the ideal would be to keep it experimental, and then we make a new PR that will make it default or no.

oddbookworm · 2024-06-30T15:08:14Z

docs/reST/ref/color.rst

+   :glob:
+   :hidden:
+
+   extra_infos/color_list.rst


extra_infos doesn't sound right to me, maybe it should just be extra_info?

Starbuck5 · 2024-07-11T07:44:21Z

I wanted to check out the style, so I switched the theme in conf.py and installed the additional package. But it fails to build.

PS C:\Users\charl\Desktop\pygame-ce> python setup.py docs --f
WARNING: This command is deprecated and will be removed in the future.
Please use the following replacement: `C:\Users\charl\AppData\Local\Programs\Python\Python39\python.exe buildconfig\make_docs.py full_generation`

Executing sphinx in subprocess with args: ['C:\\Users\\charl\\AppData\\Local\\Programs\\Python\\Python39\\python.exe', '-m', 'sphinx', '-b', 'html', '-d', 'docs\\generated\\doctrees', '-D', 'headers_dest=src_c\\doc', '-D', 'headers_mkdirs=0', 'docs\\reST', 'docs\\generated', '-E']
Running Sphinx v7.1.2
C:\Users\charl\AppData\Local\Programs\Python\Python39\lib\site-packages\sphinxcontrib\applehelp\__init__.py:24: RemovedInSphinx80Warning: The alias 'sphinx.util.SkipProgressMessage' is deprecated, use 'sphinx.util.display.SkipProgressMessage' instead. Check CHANGES for Sphinx API modifications.
  from sphinx.util import SkipProgressMessage, progress_message
C:\Users\charl\AppData\Local\Programs\Python\Python39\lib\site-packages\sphinxcontrib\applehelp\__init__.py:24: RemovedInSphinx80Warning: The alias 'sphinx.util.progress_message' is deprecated, use 'sphinx.http_date.epoch_to_rfc1123' instead. Check CHANGES for Sphinx API modifications.
  from sphinx.util import SkipProgressMessage, progress_message
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 98 source files that are out of date
updating environment: [new config] 98 added, 0 changed, 0 removed
reading sources... [100%] tutorials/ko/빨간블록 검은블록/개요
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... WARNING: unsupported theme option 'home_uri' given
done
copying assets... copying static files... done
copying extra files... done
done
writing output... [  1%] c_api
Extension error (pydata_sphinx_theme):
Handler <function update_and_remove_templates at 0x00000221BDA35670> for event 'html-page-context' threw an exception (exception: 'dict object' has no attribute 'image_relative')

---
For help with compilation see:
    https://github.com/pygame-community/pygame-ce/wiki/Compiling-on-Windows
To contribute to pygame-ce development see:
    https://github.com/pygame-community/pygame-ce
---

Failed to build documentation

Notenlish · 2024-09-05T10:03:07Z

docs/reST/modules.rst

+  Manipulate sound sample data.
+
+:doc:`ref/sprite`
+  Higher level objects to represent game images.


Game images? Why not game objects

Notenlish · 2024-09-08T08:27:32Z

I like this new docs theme. But IMO, using green based colors would be better.

Why 2 seperate colors(orange happens when hovering over a link). I think it'd be better if the docs used only blue or green for link colors.

The docs also need to use the new pygame-ce logo.

This color could be changed.

Notenlish · 2024-09-08T08:29:02Z

Would it be possible to move the contents so it aligns with the search bar?
Also can we get rid of the line to the left of contents

bilhox · 2024-09-08T08:33:11Z

The docs also need to use the new pygame-ce logo.

Yes I didn't update the branch yet.

bilhox · 2024-09-08T08:35:47Z

Why 2 seperate colors(orange happens when hovering over a link). I think it'd be better if the docs used only blue or green for link colors.

For the moment, this version directly uses the theme installed, I did no modification to it. I think I'll be moving it to custom themes so we can do changes on the colors and everything. (maybe next week)

Notenlish · 2024-09-08T08:36:11Z

Would it be possible to move the contents so it aligns with the search bar? Also can we get rid of the line to the left of contents

I was thinking about something like this
this could be done by just using position: relative; in the container and then setting position: fixed and top: [some value]; in the contents element.

Notenlish · 2024-09-08T09:01:25Z

What if we made the background of the code example white, and then simply just added background shadow?

something like this:

Notenlish · 2024-09-08T09:01:38Z

this should be 2023 - 2024 i think, not sure though

Notenlish · 2024-09-08T09:06:49Z

Colors for dark theme definitely need to be changed

Notenlish · 2024-09-08T09:10:08Z

The color contrast is bad when hovering over the items

same thing happens in dark theme too:

Notenlish · 2024-09-08T09:13:24Z

Why is there an element to purposefully add margin bottom to make the sidebar have a scrollbar, even if the sidebar contains few items.

weird choice by the theme makers

first website version

2e63052

bilhox requested a review from a team as a code owner June 13, 2024 19:52

fixes

0c2145b

damusss added docs website labels Jun 14, 2024

damusss reviewed Jun 14, 2024

View reviewed changes

bilhox added 2 commits June 14, 2024 13:54

joystick fix

d9c38c8

docs fixes for joystick and system (indentation problem)

e4a2c1f

oddbookworm requested changes Jun 30, 2024

View reviewed changes

ankith26 marked this pull request as draft July 8, 2024 14:17

Notenlish reviewed Sep 5, 2024

View reviewed changes

Notenlish mentioned this pull request Sep 29, 2024

Docs Rework #3132

Open

zoldalma999 mentioned this pull request Jan 5, 2025

add sidebar + sort modules #2225

Closed

		@@ -1,4 +1,4 @@
		.. include:: common.txt
		.. include:: ../../common.txt

Uh oh!

New website style + docs sorting modifications #2924

Are you sure you want to change the base?

New website style + docs sorting modifications #2924

Uh oh!

Conversation

bilhox commented Jun 13, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bilhox commented Jun 16, 2024

Uh oh!

Starbuck5 commented Jun 16, 2024

Uh oh!

oddbookworm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Starbuck5 commented Jul 11, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Notenlish commented Sep 8, 2024

Uh oh!

Notenlish commented Sep 8, 2024

Uh oh!

bilhox commented Sep 8, 2024

Uh oh!

bilhox commented Sep 8, 2024

Uh oh!

Notenlish commented Sep 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Notenlish commented Sep 8, 2024

Uh oh!

Notenlish commented Sep 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Notenlish commented Sep 8, 2024

Uh oh!

Notenlish commented Sep 8, 2024

Uh oh!

Notenlish commented Sep 8, 2024

Uh oh!

Uh oh!

Notenlish commented Sep 8, 2024 •

edited

Loading

Notenlish commented Sep 8, 2024 •

edited

Loading