
<html><body><div>Hi.<br></div><div><br></div><div>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.<br></div><div><br></div><div><div><b>Motivation</b>: 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: <i>"Lots of that is very old, but some is auto-generated and current. Would love help untangling the docs!"</i></div><div><div><br></div></div><div><b>Where</b>: The current iteration is hosted on my forked repo at <a rel="noopener noreferrer" href="https://brian3johnson.github.io/pywin32/index.html">Python for Windows Extensions — pywin32 305 documentation (brian3johnson.github.io)</a>. If this effort moves forward, I'll pull it down once it's built and posted from mhammond's repo.<br></div><div><br></div></div><div><b>How</b>: I am building the documentation with sphinx <a rel="noopener noreferrer" href="https://www.sphinx-doc.org/en/master/">Welcome — Sphinx documentation (sphinx-doc.org)</a> 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.<br></div><div><br></div><div><b>What</b>: 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.<br></div><div><br></div><div><b>Proposed Next Steps</b>:<br></div><div><br></div><div>1. Confirm if I move forward with sphinx. If so, confirm if we use reStructuredText (<a rel="noopener noreferrer" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html">reStructuredText — Sphinx documentation (sphinx-doc.org)</a>) or Markdown (<a rel="noopener noreferrer" href="https://www.sphinx-doc.org/en/master/usage/markdown.html">Markdown — Sphinx documentation (sphinx-doc.org)</a>) for narrative documents.<br></div><div>2. Finish formatting the existing narrative docs per rst or md.<br></div><div>3. Add docstrings to .py source files to generate API docs.<br></div><div>4. Convert some of the "samples" embedded in the source files to "How-tos".<br></div><div><br></div><div>I have more ideas and suggestions, which I can share in an Issue, PR, or on this mailing list.<br></div><div><br></div><div>I look forward to hearing what you think.<br></div><div><br></div><div>Sincerely,<br></div><div>Brian</div></body></html>