Hi Brian,
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?
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?
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.
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.
So really, the big unknowns for me that need answering are:
* How exactly do the autoduck comments get handled as they change?
* How does adding docs to the .py files overlap with adding type hints?
* Does it replace the existing system rather than adding yet more
complexity to it?
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!
Mark
On 6/12/2022 12:56 pm, Brian Johnson wrote:
Hi.
I took a stab at upgrading and "untangling" the documentation. I am
willing to work on this documentation "untangling" project. Before I put
more effort into it, I would like to get feedback from Mark and other
contributors on what I'm proposing. If so, I'll log an Issue and/or pull
request.
*Motivation*: I need to work with a COM server application and want to
use python. I found it challenging to find documentation and examples.
Also, Mark mentioned this in the repo README: /"Lots of that is very
old, but some is auto-generated and current. Would love help untangling
the docs!"/
*Where*: The current iteration is hosted on my forked repo at Python for
Windows Extensions — pywin32 305 documentation (brian3johnson.github.io)
<https://brian3johnson.github.io/pywin32/index.html>. If this effort
moves forward, I'll pull it down once it's built and posted from
mhammond's repo.
*How*: I am building the documentation with sphinx Welcome — Sphinx
documentation (sphinx-doc.org)
<https://www.sphinx-doc.org/en/master/> to update the narrative docs and
automate or semi-automate the pywin32 API reference. I am using the
default theme. I'm using reStructuredText (.rst) for the docs.
*What*: I included all the existing narrative documentation from the
CHM. Most of it remains unformatted, except for a couple of docs. I
added a Home page, Installation, Support, and Resources pages, and the
start of a Getting Started Tutorial.
*Proposed Next Steps*:
1. Confirm if I move forward with sphinx. If so, confirm if we use
reStructuredText (reStructuredText — Sphinx documentation
(sphinx-doc.org)
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>) or Markdown (Markdown — Sphinx documentation (sphinx-doc.org) <https://www.sphinx-doc.org/en/master/usage/markdown.html>) for narrative documents.
2. Finish formatting the existing narrative docs per rst or md.
3. Add docstrings to .py source files to generate API docs.
4. Convert some of the "samples" embedded in the source files to "How-tos".
I have more ideas and suggestions, which I can share in an Issue, PR, or
on this mailing list.
I look forward to hearing what you think.
Sincerely,
Brian
_______________________________________________
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
