Books plugin documentation update

[S-Haime]

Documentation for the books plugin.

Adding @joemull as a reviewer since you volunteered and @ajrbyers as this is your plugin.

Minor points:

• Monthly reporting is currently broken in the plugin. Issue is open, but this is therefor not included (but will be similar to regular metrics).
• What is the recommended size for books covers? Same as journal covers?
• Currently missing the Sphinx files and conf.py (I understand how it works in theory as its documented well enough + can see how it works on JW main and imports, but it might be good for me to see someone do it first, before messing about).

[joemull]

Thanks @S-Haime--this is really good! I especially like the contextual detail you provide. Things like this show you are thinking through the questions people will have, which of course you are, but just wanted to say so explicitly because it is great:

Make sure that the filename of the file uploaded is consistent and correct. Whilst Janeway will change the filename to the title internally, depending on the application used to open the document after download, the original filename might still be visible. Google Chrome is an example of an application that might still display the original filename in its reader toolbar, as displayed in the image below.

I added a few comments below.

In terms of building the documentation, I don't think we have a setup for RST on plugins yet. We'd have to configure that if we wanted it to show up on readthedocs.io. I can do that and help you with it @S-Haime so if that's what we want to do. Thoughts @ajrbyers?

Another option: Since we are phasing out RST, one easy short-term solution that keeps us from having to add more RST configuration is to just put this in a markdown file, something like USER_GUIDE.md at the top level of the repository. With an images folder replacing nstatic and a link from the main README.md file so people can read the docs on GitHub. Basic but functional. What do you think?

[joemull]

Might be a missing reference to this note?

[S-Haime]

Should be fixed now in .md

[joemull]

These images are great in terms of the content they cover and their frequency.

But for the long term I'm hoping we can take narrower versions of them, so they fit in a narrower container on our future docs site. We currently let the text and images run very wide in our documentation, but this isn't best practice and our future documentation site will hopefully use something more in the range of <580px for prose and <960px for content.

[S-Haime]

(I haven't addressed any of the images, as I imagine we'll want to look at this as part of the website building.)

[ajrbyers]

This is great. As @joemull mentioned we are phasing rst out so it may be worth converting this to md. For this file, as there are no toctrees it should be relatively simple.

[joemull]

Thanks @ajrbyers.

@S-Haime I think that means we should do this:

Another option: Put this in a markdown file, something like USER_GUIDE.md at the top level of the repository. With an images folder replacing nstatic and a link from the main README.md file so people can read the docs on GitHub.

Let me know if I can help. I will go ahead and give this PR the status of Changes Requested.

[S-Haime]

The .rst file can be retired at some point now :)

[joemull]

Thanks @S-Haime -- looks good to me. I added another commit to delete "Books.rst," if that's alright with you. Over to you for the second green tick @ajrbyers.