Refractoring the documentation

[arihant2math]

Currently the documentation is scattered, and I feel that it would be much easier to work on the documentation if it was restructured. For example, the is_api overview documentation is at is_api/doc and is written in HTML, while the python com and win32 docs are in /com/help and win32/help respectively and are written in a combination of HTML and "d", which seems to be related to autoduck in some way, and the adodbapi directory does not seem to have a documentation directory at all. I would suggest that one of the following options is perused:

1. Continue to use autoduck but migrate everything to HTML
2. Migrate to sphinx+autodock extension

[mhammond]

Thanks for your interest!

A .d file is like any other autoduck file, but instead of being embedded in c++ source files it's a stand-alone file. Autoduck is somewhat like a pre-processor - it parses the source files and .d files, and generates a HTMLHelp project, which ends up creating html in a .chm file - the html can be extracted out from that, which is how https://mhammond.github.io/pywin32/ exists. We don't have the source-code to autoduck.

With that in mind:

• Continue to use autoduck but migrate everything to HTML

I'm not sure what you mean here - migrate what exactly? Most docs which aren't processed by autoduck already are HTML.

• Migrate to sphinx+autodock extension

What would that mean to all the existing autoduck markup?

[arihant2math]

Sorry for the extremely late reply.

A .d file is like any other autoduck file, but instead of being embedded in c++ source files it's a stand-alone file. Autoduck is somewhat like a pre-processor - it parses the source files and .d files, and generates a HTMLHelp project, which ends up creating html in a .chm file - the html can be extracted out from that, which is how https://mhammond.github.io/pywin32/ exists. We don't have the source-code to autoduck.

With that in mind:

• Continue to use autoduck but migrate everything to HTML

I was unaware Autoduck would parse the C++ files for additional docs. This would cross out option 1.

• Migrate to sphinx+autodock extension

What would that mean to all the existing autoduck markup?
An autoduck extension would support autoduck syntax etc. and would parse the source files. However sphinx has a feature called autodoc, which does essentially what autoduck does. Unfortunately it only supports python docstrings, making option 2 close to impossible.

Potentially, doxygen can be used. If configured with macros, we can make it interpret things like @pymeth correctly, it also supports parsing C and C++ files (and python). The only catch here is the way doxygen distinguishes between what to include vs exclude. Doxygen does not include comments that start with // and many of the current doc comments do start with //. It is possible this behavior might be able to be modified.

[Avasam]

Adding to this conversation: Type annotations live in https://github.com/python/typeshed/tree/main/stubs/pywin32
My main gripe right now is searchability, but typeshed helps with that (although very long term stubs probably shouldn't live there forever)

In the (very) long term, it'd be great if type stubs for C-extension modules could be generated first party. So far everything I've seen (numpy, OpenCV, PySide/Qt) all use custom solutions based on their documentation + extra custom processing steps.

Relates to #1535

[Avasam]

There's a lot of very interesting discussion in swig/swig#735