Re: [python-win32] pywin32 Documentation

[Brian Johnson]

Hi Vernon.  I made an initial pass with moving it. Python ADODBAPI quick reference — pywin32 305 documentation brian3johnson.github.io I have mot worked through cleaning up the format nor scrubbing it for old code or dead links.  Thanks! Brian On Dec 6, 2022, at 7:33 AM, Vernon D. Cole <vernondc...@gmail.com> wrote:  The most important document for adodbapi is in Markdown. (That's an improvement - - I wrote it in .odt) so if that helps the decision, I would say lean toward that direction. It needs to be linked / indexed in where people can actually find it. adodbapi/quick_reference.md If we make an actual .docs directory, it should move there. It also needs an edit pass to get rid of obsolete references to Python 2 and to check that the external links still work and so forth. I'll add that to my to-do list. On Mon, Dec 5, 2022 at 6:57 PM Brian Johnson <br...@brian3johnson.me> 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). 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) 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)) or Markdown (Markdown — Sphinx documentation (sphinx-doc.org)) 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