Hi Mark.Thank you for the feedback. My responses in-line below. Also...Example of reformatted narrative doc:Quick
Start to Client side COM and Python — pywin32 305 documentation (brian3johnson.github.io)Example of api docs
generated from .py docstring:adodbapi package — pywin32 305 documentation (brian3johnson.github.io)Note: the TOC
sidebar still needs work. Thanks for your interest. I probably should have written more about this earlier. From
my POV, the main considerations I have are:1) Much of the documentation is inside the c++ source formatted via
"autoduck" style comments. I really don't want to abandon this documentation, but I don't think it's
helpful in a sphinx-based world?BJ > I would not want to abandon this either. I don't know much about Autoduck
apart from gathering that it generates documentation from the C++ source. There may be an approach using SWIG
with some modifications within the C++ source code:https://www.swig.org/Doc4.1/Python.html#Python_nn65 2) There's
no where near as much docs embedded in the .py code, which is something that we can address. However, some work
has started on https://github.com/mhammond/pywin32/issues/1913, which hopes to add type annotations - see also
yesterday's mail to this list on this topic. While I'm not quite sure exactly what approach is being suggested
for that, it seems possible it will have at least *some* overlap here?BJ > Yes, I saw the email about this
yesterday. Good news is that those type hints/annotations can be used by sphinx to generate the api docs. In
fact, this is something I would have done as part of this documentation effort.3) Working out a good layout in
the repo for docs is also important, but I don't forsee any real obstacles here - as you mention, a TOC etc are
important. .rst seems like a perfectly reasonable format for hand-written docs, and given there aren't really
that many hand-written docs in the tree which remain relevant, hand-converting them to largely unformatted
markdown seems reasonable in the first instance. There's always going to be a bit of tension between keeping the
docs organized and trying to keep the docs fairly close to the implementation they are documenting, but we can
manage that.BJ> Agreed.4) I'd want to kill the existing tooling entirely as it's just going stale. Eg, the way
https://mhammond.github.io/pywin32/ is built is interesting (it decompiles the .chm!) but that seems like a
dead-end - I suspect that at some point it will end up extremely difficult to build that .chm in the first place
- finding the Windows HTML Help compiler today is difficult enough.BJ> I agree with this as well. In fact,
sphinx can generate HTMLHelp for compiling to CHM if you still want to have a CHM file available.So really, the
big unknowns for me that need answering are:* How exactly do the autoduck comments get handled as they
change?BJ> Maybe via SWIG. More research needed.* How does adding docs to the .py files overlap with adding
type hints?BJ> Overlaps perfectly.* Does it replace the existing system rather than adding yet more complexity
to it?BJ> ReplacesI'll look a little more at your repo over the next week or so, but I'm currently a bit short
on time, but really am interested in improving the docs, so thanks!BJ> Sounds good! Thanks!
_______________________________________________
python-win32 mailing list
python-win32@python.org
https://mail.python.org/mailman/listinfo/python-win32
