search

mhammond / pywin32

Python for Windows (pywin32) Extensions
4.91k stars 783 forks source link

Convert HTML project documentation to Markdown #1141

Open zspitz opened 6 years ago

zspitz commented 6 years ago

It would be more easily usable in GitHub. However, it would mean an additional step in generating the CHM file.

Is this a good idea?

I would be willing to submit a PR.

mhammond commented 6 years ago

I'm open to that, but I'm not quite sure what you are proposing yet - can you please outline what such a PR would look like?

zspitz commented 6 years ago

@mhammond There are 28 HTML files scattered in various places within the project, documenting different aspects of PythonWin.

I would first run some kind of HTML-to-Markdown converter, and then go over each file individually to make sure the Markdown matches the original HTML. The PR would replace each of these HTML files with the corresponding Markdown file.

Some or all of these files end up in the documentation which is installed with PythonWin in the form of a CHM file, which is why I assume an extra build step will be required to convert the Markdown back to HTML before packaging into a CHM.

Another point: once these files are available as Markdown, perhaps a more appropriate place for them would be in the project's wiki section, assuming it is possible to build a CHM from the wiki pages. It should be a simple matter of copy-pasting the Markdown into the Github editor.

mhammond commented 6 years ago

That sounds reasonable to me, although it is worth noting that the build process generates many HTML files from autoduck comments in the source-code and from various .d file spread throughout the tree, so having the .md files on the wiki will always be a small subset of all the documentation in the .chm. That said though, having the hand-edited HTML files in .md format sounds like a win, so long as the generated output is still reasonable.

Avasam commented 3 months ago

So here's a fun fact: Markdown supports simple HTML. It depends on what your viewer allows, but GitHub supports a lot. So just changing the file extension after generation could be a valid option if all you want is to make them readable when browsing the repo in GitHub.