GSoD Preview of Module Documentation

To make it easier to see how the module documentation improvements that are part of the Google Season of Docs will look I have uploaded them to:

https://tryton-gsod.readthedocs.io/


Here you can see roughly what the documentation will look like, and you will be able to see how the markup, formatting and other features will appear.

Anyone who is finding the reviews on codereview.tryton.org difficult to read can use the link above to look at the documentation. For anyone who cannot use codereview.tryton.org, if you want to leave any comments below please do.

There is one important thing to be aware of:

Thanks!

4 Likes

Thanks for putting it online, it reads much better!. Just one overall question about the markup. Is it possible to distinguish more between menu entries and the normal text?

E.g. when you look at the sentence (https://tryton-gsod.readthedocs.io/projects/modules-account/en/latest/usage.html)
“In Tryton you do this by using the items found under the Financial ‣ Entries menu item.” there is not much difference in text size or color between the text and Financial ‣ Entries

The way it appears is based on the sphinx theme used, which by default on readthedocs is the readthedocs theme, but I think it does have some configuration options and can be customized. So I think that should be possible.

We do not want to make any customization because it will cost too much to maintain over more than 150 repositories.

1 Like

Totally agree with that. There are other ways to make it more clear.

I’m just thinking about it and had some ideas:

  1. put the menu entries on a separate line (lot of work because different sentences have to be rewritten
  2. underline, italic, bold, other font (styling customization)
  3. add some extra space before and after
  4. add [ … ] or ( … )
  5. what does :guilabel: do?

Thanks for your suggestions, I think the most promising of these are 1 and 4:

Both of these could be done by simply updating the text in the .rst files.

The problem with options 2, 3:

For these I think you would need to do some kind of additional customization, such as adding a style sheet, or similar, which is something I think we want to try and avoid.

The last option, 5:

This would look good (it can be seen used for the “Open related records” button in the first tip in the party/doc/usage.rst), however I don’t think it is intended to be used with menu entries so I would prefer to stick with the :menuselection: role.

Hmm, I was already thinking in HTML and there you can add some extra &nbsp tags to create a bit more space.

All of them are suggestions, do with it what you want and keep things as standard as possible. I’m already very happy with the work you’ve done! Awesome work!

1 Like

Please do not use the temporary rendering link on the forum. This does not create knowledge for the long term as these links are temporary and will not be maintained.

I saw a whole bunch of changes made the last days. Is the documentation on the test-readthedocs also getting a update?

Thanks!

Yes, I’ve just been reviewing, editing and updating the proposed changes to each of the basic modules’ documentation based on the feedback that I’ve received so far. I was waiting until that was done before I updated the previews.

As it’s pretty much done now, I am aiming to update the previews tomorrow.

Thanks! :+1:

I’ve just finished updating the preview documentation to the latest version on https://tryton-gsod.readthedocs.io/.

:warning: If you’ve looked at it before, you may need to clear your browser’s cache, or reload it a few times, to see the most recent version.

If you spot anything wrong with it, or have any suggestions on how it could be improved please don’t hesitate to mention them here, or add them to the appropriate place on codereview.tryton.org.

Thanks!