[WIP] adding HARKmanual in markdown to RTD

[sbenthall]

Getting the HARKmanual into sphinx/readthedocs, with markdown source, as per #409.

For me, simply converting the LaTeX version of the manual into markdown with pandoc resulted in a corrupted markdown file that could only be partially read by Sphinx.

So I've started working at a different way: using pandoc to turn the available, complete HARKmanual.html into a markdown file.

The generated markdown has [line breaks in its image tags](https://github.com/sphinx-doc/sphinx/issues/6797). I've worked these out by hand.

There are still an unknown number of issues preventing the file from being parsed and formatted by sphinx.

[llorracc]

I have a script, in HARK-make, that generated HARKmanual.md. I found, as you did, that pandoc did not seem to work at all for the direct conversion of LaTeX to markdown, but did a not-too-terrible job converting from the html version to Markdown. The script is makeWeb-HARKmanual-And-Contributing-To-HARK.sh and dates back to a time when the “Contributing” instructions were in the manual, and to satisfy my hatred of having the same content in two places, I modified the HARKmanual so that the Contributing section was written out as a separate standalone file, which could be used for the “Contributing” section. This is obsolete now; if the Contributing section is still in the HARKmanual, it should be replaced with a link to our now-curated “Contributing.md” file. But, as I discovered a few days ago, one flaw of pandoc is that it does not preserve internal links (like, to references or equations or sections of the document) in documents that it converts. Before you spend any more time hand-editing the Markdown version of the manual, we should make an executive decision about where the *master* version of the manual should be. Andrij seems to think that it should be in markdown. Sounds like you think rst. The advantage of LaTeX is that it is more powerful and can do things the others cannot. Maybe with a bit more work we could figure out how to generate an appropriate rst and/or markdown file from the LaTeX. In any case, let’s have a discussion of all this before you do any more hand-editing of any version of the manual.

…

On Sun, Feb 9, 2020 at 3:02 PM Sebastian Benthall ***@***.***> wrote: Getting the HARKmanual into sphinx/readthedocs, with markdown source, as per #409 <#409>. For me, simply converting the LaTeX version of the manual into markdown with pandoc resulted in a corrupted markdown file that could only be partially read by Sphinx. So I've started working at a different way: using pandoc to turn the available, complete HARKmanual.html into a markdown file. The generated markdown has [line breaks in its image tags]( sphinx-doc/sphinx#6797). I've worked these out by hand. There are still an unknown number of issues preventing the file from being parsed and formatted by sphinx. ------------------------------ You can view, comment on, or merge this pull request online at: #500 Commit Summary - adding HARKmanual in markdown to RTD. Needs more hand-editing. #409 File Changes - *M* Documentation/index.rst <https://github.com/econ-ark/HARK/pull/500/files#diff-0> (6) - *A* Documentation/manual_md/HARKmanual.md <https://github.com/econ-ark/HARK/pull/500/files#diff-1> (1709) Patch Links: - https://github.com/econ-ark/HARK/pull/500.patch - https://github.com/econ-ark/HARK/pull/500.diff — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#500?email_source=notifications&email_token=AAKCK76235TC3JPHACZ3OQLRCAEHRA5CNFSM4KSB24G2YY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4IMCGSZQ>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKCK7YYO6FSVD5TDET6VJ3RCAEHRANCNFSM4KSB24GQ> .

-- - Chris Carroll

[sbenthall]

Chris, I was going on the discussion on issue #409, which was active in November.

There, you persuaded me that it's best to use markdown for a temporary RTD version of the manual.
#409 (comment)

[sbenthall]

With the manual now hosted online at

http://econ-ark.github.io/HARK/Documentation/HARKmanual/

we seem to have punted on the problem of getting the manual into either Markdown or RST into RTD.

Unless somebody would like to reopen that discussion, I'll close this PR soon to clean up the issue tracker.

[llorracc]

I know you made a link somewhere to the new manual. If you have verified that there are no references anywhere to the markdown version anywhere else, go ahead and close this.

PS. Eventually probably we should have a unified system/structure for the documentation, rather than having a LaTeX -> HTML -> gh-pages procedure for HARKmanual and something else (RST or Markdown) for the rest. But I see no urgency to that.