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 <https://github.com/mhammond/pywin32/blob/main/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) > <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
