I looked into the docs build error. It's root cause is that now it's trying to pull from multiple different places for the micropython module.

I've tested the following solution locally and it appears to be working:

1. Delete: https://github.com/adafruit/circuitpython/blob/main/docs/library/micropython.rst. Sphinx will pull from the stubs for anything that it can, so it no longer needs this static rst file it will pull from the new static .pyi file. Which in hindsight is actually kind of nice to have 1 true source of the info rather than multiple. There are a handful of other micropython features in this file currently that are all marked as CIRCUITPYTHON REMOVE which seems to disable them from appearing on the final docs page. If there is a desire to keep those in the repo in some fashion then they would need to be moved to the .pyi if we use this solution, hopefully the same REMOVE thing can be done from there. If they aren't used by our docs, I'm not sure we have a need for them in the repo though personally.

2. Change these lines:

   circuitpython/docs/library/index.rst

   Lines 54 to 57 in 473557c

   	.. toctree::
   	:maxdepth: 1
   	micropython.rst

   to this:

:doc:`../../shared-bindings/micropython/index`

With those changes the final docs pages remain almost the exact same and seem to build successfully.

The one visual difference is on this page: https://docs.circuitpython.org/en/latest/docs/library/index.html "micropython" appears as part of the link instead of in a code block.

Currently live docs:

Local test build doc with these changes:

There might be a way to get the code formatting back, but I am not sure. It took me a decent amount of fiddling to figure out how to link to the right place so I decided to skip trying to match the code format syntax. I could try to look for that though if it is preferred to keep that styling.

Okay I tried out what you described and locally got it building and it seems good...but the only problem is it is now putting micropython as a module in Core Modules, which we don't want.

I think having it pulled in via stubs makes the docs assume that it is inside of shared-bindings. I just noticed also the URL that the micropython docs ends up at is different:

Currently live:

/docs/library/micropython.html

With this PR change:

/shared-bindings/micropython/index.html

I'm not sure how to fix it. I think that it's getting picked up by this autodoc https://github.com/adafruit/circuitpython/blob/main/shared-bindings/index.rst?plain=1#L24-L28 but I don't know if it's possible / how to make an exclusion for micropython but if we did exclude it from here then we would need to somehow explicitly add it somewhere else for it to be available in the docs. I'm not sure if it's possible, or if it would work to dump the .pyi files back at doc/libraries/micropython/ during the build, but maybe?

Personally I think it's okay to have micropython appear in 'core modules' instead of 'standard libraries', or at least I can think of no downside other than the URL changing, so any cached copies of that might become dead links. I don't know the real history of it, but looking at the structure of the different files and how docs/stubs build now it feels to me like those might have been originally separate due to the fact that those modules didn't exist somewhere with our docstrings that ultimately are what the docs (and .pyi files) get built from. With this change we now do have a place with our docstrings (the new static stubs file), so it makes sense to me that it would move to the same place as all the other docs that originate from docstrings rather than .rst files.

Okay cool. I kind of was at the same place as you with not really sure how to get it to replicate the current site layout. But if you are okay with it being in Core modules then that works for me!

The last commit adds a redirect from the old location to the new, so dead links shouldn't be a problem.