Store user guide source in git

[EJEP]

Storing the user guide source code in the git repository would allow contributors to apply minor changes via pull requests. This would also have the advantage of distributing a versioned copy of the user guide with the source code.

Going forward, using a framework like that used by ReadTheDocs would allow multiple versions of the user guide to be hosted as web pages rather than as pdfs. Something like this could be included on the new website or via a service like ReadTheDocs.

[djboersma]

ReadTheDocs is fantastic, but as I understand it, it requires us to rewrite our entire user guide in "markdown". That is quite a bit of work! Part of the work can probably be done by an automatic converter (first hit in google is "pandoc"), but I do not expect these tools to work flawlessly, so we would then need to read and edit/correct everything afterwards.

We could try, but if it looks like it is going to be time consuming, then it won't happen. We lack manpower! Would you have time and resources to try this yourself?

[EJEP]

I am happy to put the initial work in to convert the user guide source into a different format. I would suggest ReStructured Text rather than markdown as it is a bit more powerful for writing technical documentation but maintains readability. ReStructured Text is supported by a variety of documentation generators like markdown is. In my experience pandoc is a very useful tool.

[dsarrut]

Interesting ! However, is ReadTheDocs allow online text editor to allow users to do quick&easy web only pull request ?

[EJEP]

ReadTheDocs does not. However, it can hook into the GitHub so that when a commit is made to the source code, the web page is rebuilt. Links can be provided on each page to the source file on GitHub. The GitHub editor can then be used.

[mojca]

If you are thinking about porting the documentation, my super strong vote goes to AsiiDoc.

Don't use MarkDown unless you have very very very basic requirements, as almost anything beyond basic paragraphs, titles, images and just the most basic tables requires one kind of extension or another, usually simply hardcoding raw html, which is a difficult one to get rid of. AsciiDoc is really nicely structured and asciidoctor creates really nice html documents out of the box.

And yes, if you put the docs on GitHub, users can simply press the "Edit" button and automatically make a pull request (they need to have an account on GitHub, but they don't need to know any git whatsoever).

[EJEP]

I would rather use ReStructured Text as it is directly supported with readthedocs and looks a little more readable in the source compared to AsciiDoc while remaining similar enough in syntax to AsciiDoc to be understandable. I used http://hyperpolyglot.org/lightweight-markup for a comparison as I have no experience with AsciiDoc. Please tell me if this is not a fair comparison.

That said, I very much want to avoid a situation where there is a barrier to entry to maintaining and contributing to the user guide.

[dsarrut]

@EJEP could you please setup a readthedocs trial as a specific branch PullRequest in the gate source code (in a doc/ folder) ? A quick and dirty first attempt (no need to copy all the doc of course) to see how it can look like ?

[EJEP]

Sure. Could you send me / give me access to the documentation source, so I can avoid doing too much typing? This isn't essential to get a first attempt going. I will need to check if I can import the repository to ReadTheDocs without being a member of the GitHub 'organization'

[dsarrut]

thanks a lot ! The doc source is the wiki (not git): http://wiki.opengatecollaboration.org/index.php/Users_Guide For deploying the readthedocs site on the readthedocs server, you may try with your own GitHub account by cloning the gate repo, no ?

[EJEP]

Oh, yes, of course! I'll just give it a test name of some sort

[EJEP]

An example site is available at https://gate-demo.readthedocs.io/en/readthedocs/index.html.

The pull request is #218

[dsarrut]

Very interesting thanks a lot ! Some comments:

• there are some ads on the readthedocs site
• online edition seems feasible via the bottom right small menu. I tried the 'edit' link. It redirect nicely to the git page of the rst file. I tried to propose a change via a PR, but it fails with 404 ...
• the search bar is useful (select page + highlight searched terms)

We will discuss with people in the collaboration about this idea and let you know.

thanks again, David

[EJEP]

Regarding ads, it is possible to opt out of displaying them - see here.

On the pull request issue, there was a box ticked in the settings restricting editing to collaborators. That may be the problem, but I think the box is just for the GitHub wiki

[mojca]

I'm not too familiar with readthedocs in particular, but I would like to point out that there are two independent questions / issues. The first and the most important one that's probably being suggested here is having documentation in a markup language that's easy to render for either web or PDF, next to the sources. (In my opinion there are only two really suitable formats which offer sufficient flexibility and complexity when needed: restructured text and asciidoc. I'm a big fan of the second, but rst is also ok. I did not check the quality of the PDF you can get from rst when you enter math and how hard it is to change the layout style etc.)

The second part of the question is where to host the documentation once it's in a suitable format. I would probably use readthedocs as a secondary / backup location and host the primary pages on github or wherever your main site will be. So personally I would not worry about ads too much, but of course you can select the support the project, ending in win-win situation for both if you like the service.

It's important to keep this in mind when you said you'll discuss this within the organisation. Even if you don't like a particular service, having the documentation nicely stored in the same repository as your sources and being able to produce high quality PDFs would be an important step forward.

@dsarrut: do you get the same kind of error if you try to edit one of the pages from, say, https://mesonbuild.com/ (the first one that came to my mind)?

[EJEP]

Was a decision ever made about this?

[dsarrut]

yes: we are switching to readthedocs (it was decided at the beginning of the summer). It is still work in progress, but it should soon replace the wiki. Hope within next weeks ...

[djboersma]

When i googled for "readthedocs opengate" I landed on this page: https://readthedocs.org/projects/opengate/

When I click on "latest" then I land on our docs. But there is also a "stable" link, which leads to a useless page that might be discouraging for any interested new user. We either need a single link (to what is now called "latest") or make sure that "stable" points to something useful.

[tbaudier]

Hi @djboersma

According to the doc, the stable link exists because the project contains tags and it point to the latest tag (but the doc does not exists at this moment): https://docs.readthedocs.io/en/stable/versions.html

I deactivated the stable version for the moment in the parameters and I will reactivate it when the next version will be ok.

[tbaudier]

If you want access to the readthedocs parameters, send me an email with you readthedocs account name

[dsarrut]

done ! Thanks to everyone