Vernon.The fantastic work is all yours. I simply started converting your quick_reference.md to reStructuredText.-BrianOn Dec
6, 2022, at 7:52 AM, Vernon D. Cole <vernondc...@gmail.com> wrote:Brian:I did not see your entry before writing mine.
Fantastic work on the adodbapi calling interfaces! I think that there is still a need for something like the quick_reference,
so that there can be discussion about things like the extensions. The ability to switch between paramstyles is probably still
unique. There was discussion in the dbapi community that it was impossible to do. Sometimes that sort of thing is best
presented in paragraph format.I still have the original source for Python Programming on Win32 (thank you, Mark) but O'Reilly
was not interested in publishing a second edition several years ago. Perhaps it is time to ask them again.On Tue, Dec 6, 2022
at 3:02 AM Brian Johnson <br...@brian3johnson.me> wrote: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
_______________________________________________
python-win32 mailing list
python-win32@python.org
https://mail.python.org/mailman/listinfo/python-win32
