HTML version of the manual

[lornajane]

This PR contains a (very minor!) amendment to the manual, and some scripts and supporting code to enable us to produce an HTML version (probably to then include in the website repo, but all the work is done by files in this repo). You can see how things are looking here: http://web.lornajane.net/manual.html

Fixes rst2pdf/rst2pdf.github.io#2

[akrabat]

Fantastic to see this work. Thanks.

Do you have any ideas on how to we can automate getting this into the docs site?

[akrabat]

Note: We'll need to think about images too when publishing to the website as the HTML generated for the biohazard image is this:

<img alt="biohazard" src="../rst2pdf/tests/input/images/biohazard.png">

[lornajane]

I think it might be worth moving the manual source, styles and other assets such as images to their own directory.

[akrabat]

I think it might be worth moving the manual source, styles and other assets such as images to their own directory.

Agreed. Do you want to do that as part of this PR or do you want me to merge this and then work on the next one?

[lornajane]

I'm not really clear how we're publishing it yet so I'm not clear on how to automate the publishing

[lornajane]

I can move the assets if you think we're close enough. What relies on the path to the existing manual?

[ralsina]

Let's merge it and then iterate with it already merged? No point in having PRs hanging for so long when they are this nice.

[akrabat]

I can move the assets if you think we're close enough. What relies on the path to the existing manual?

I think that the next step is to make both manuals build to a self-contained directory and then work out how to get them onto the website.

I think that the path to the existing PDF manual is only relied on in the sense that it's all over Google.

[lornajane]

I moved the files, but it breaks the roles/directives that I made and I'm not sure why. Pushing the branch for now and hoping that either someone has advice for me or this all just makes more sense another day! Definitely don't merge this one :)

[lornajane]

OK, try this! Run the doc/gen_docs.sh script and observe the HTML, PDF and manpage(?) versions arriving in doc/output. The main manual source is still in doc/ but the styles, images and other ingredients are in doc/assets so it's obvious what's decoration and what's source.

I also rebased as github was showing some conflict warnings.

[akrabat]

Was your rst2man installed via apt? I don't have it, but I do have rst2man.py when I did pip install docutils.

[akrabat]

I get an error message about a missing file with the rst2pdf call:

$ ./gen_docs.sh
[ERROR] image.py:112 Missing image file: /Users/rob/Projects/python/rst2pdf/doc/assets/biohazard.png

This assets/biohazard.png file is also used in the generated HTML:

<p>This <img alt="biohazard" src="assets/biohazard.png" /> means you have to run.</p>

From what I can tell, this is the only external dependency we have in the HTML file that'll need to be transferred to the website.

[lornajane]

I don't know what rst2man is or what we use it for, it was already there. I think it creates something that is used to generate the command output listing in the manual (and indeed on the command line)

[ralsina]

It creates what is called a "man page" which is the standard documentation for command line tools in unix-like operating systems.

…

On Sun, Dec 16, 2018, 5:44 PM Lorna Jane Mitchell ***@***.***> wrote: I don't know what rst2man is or what we use it for, it was already there. I *think* it creates something that is used to generate the command output listing in the manual (and indeed on the command line) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#697 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAGK6cKxCOix_MU_urelS7I7fYLwD_Xks5u5rCrgaJpZM4YJLRt> .

[lornajane]

Ah, I know about man pages but I didn't know we had one! Is that also what's used in creating the "Command line options" section of the manual? Does anything else use that output apart from this process? I'm not sure if I'm breaking things by moving files.

[lornajane]

I've added the missing image, and split the outputs into a subfolder per format in an attempt to make it obvious which things we need to copy for which format. For PDF, it's self-contained, for HTML we need the "assets" folder too that I've added there and the build script copies the image in.

Known bug: I've broken the coverpage on the PDF version. The document has picked up the right title but the coverpage doesn't seem to know what to do and shows {{title}} - I can easily hardcode it though as it's the last thing that I know will block us accepting this PR.

[akrabat]

This is great. No errors and the biohazard image is displayed in the HTML output in my browser.

I've raised a PR against your branch to make rst2man work when it's installed via pip.

Interestingly, {{title}} on the PDF cover page works for me when I build locally. Does the test_custom_cover test work for you?

[akrabat]

man rst2pdf doesn't do anything on my machine. Does it do something when rst2pdf is installed using a Linux package manager?

[ralsina]

The usual "python setup.py install" doesn't put the man page anywhere useful. But if you do man ./doc/rst2pdf.1 (assuming you have generated it, it would work). In operating system packages that man page would be placed in the right directory for it to work.

…

On Sun, Dec 16, 2018 at 6:56 PM Rob Allen ***@***.***> wrote: man rst2pdf doesn't do anything on my machine. Does it do something when rst2pdf is installed using a Linux package manager? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#697 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAGK5Odzcx248B0BP8A4UrnGakyYHtGks5u5sFugaJpZM4YJLRt> .

[lornajane]

No, the test_custom_cover doesn't work for me. I thought I had a passing test suite though so I'm not sure what happened

[lornajane]

On my local platform the test was working (but the hash isn't known as good) until c263dec when it looks like we fixed something but it caused the templates to stop working ... only on my platform though if the main build isn't failing and @ralsina clearly thought he had fixed it! I am not sure what to do next as this is now the only thing blocking this issue (I think?)