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) > <https://brian3johnson.github.io/pywin32/com/QuickStartClientCom.html> > *Example of api docs generated from .py docstring*: > adodbapi package — pywin32 305 documentation (brian3johnson.github.io) > <https://brian3johnson.github.io/pywin32/adodbapi/apidoc/adodbapi.html> > *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> Replaces > > I'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
