GSoD Preview of Module Documentation

Communication
1

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
2

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

3

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.

4

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

1 Like
5

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?
6

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.

7

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
8

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.

9

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

Thanks!

10

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:

11

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!

12

hi, first thank for improving the docs.

I am wondering, will the “Edit on GitHub” link point to the actual source file in the repository on hg.tryton.org?

13

When the documentation gets committed and is available on docs.tryton.org there is no Edit on Github link. That link is just there because of the way that I setup the preview documentation.

Some of the documentation has now been committed and is available on docs.tryton.org, for example:

14

Now that all the documentation has been committed I am removing the preview.

All the changes to the documentation are now available on:

https://docs.tryton.org/

5 Likes
15

Thank you so much for your work on our documentation. It improved a lot with your contributions!

1 Like
16

Thank you David, and thank you all those who reviewed @dave’s work.

1 Like