Sepal Buttons/Icons

[BuddyVolly]

I am starting to create screenshots of the SEPAL Button/Icons and will put them under _images/icons. They can be easily used within the RST by substitution as explained here: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions

An example is:
Once logged into SEPAL, open the recipe menu (1) by clicking on the |recipes| button at the top left of the SEPAL start screen. Within the recipe menu (1), select CCDC, which opens a new SEPAL recipe tab (2).

.. |recipes| image:: ../_images/icons/recipes.png
:width: 4%

Note that width at 4% seems to be a good size for the image.
This is happening on the CCDC branch right now

[12rambau]

I'd prefer not to use inline images for the following reasons:

• Usually, the users' problem (the one that is helped so far) is not "what is the button" but "where is the button". As long as the documentation is not fully translated, it will be the only way for non-English speakers to follow what we do using only the images. So for button, it's really important to use a full window screenshot and do a circle/rectangle around it.
• Also Sphinx embed 3 main styling directive: :code: for things coded (I use it in this documentation as things you need to type or folders), :guilabel: for buttons and label, and :kbd: for keyboard buttons (use correct role for btn and keyboard press #63). they can easily cover our needs and they are ready for pdf transformation (https://github.com/openforis/sepal-doc/milestone/1). If you think it's unclear then we can add a "how to use this documentation" section.
• On my days off, I'm working on the dark theme of pydata-sphinx-theme (Set up a Dark theme pydata/pydata-sphinx-theme#501) to answer move to the dark side  #29. If we use images instead of the sphinx interpreted directive we'll get funny results.
• I created the :icon: to write fontawesome icons in our document that as a start (https://docs.sepal.io/en/latest/team/contribute.html#icon) but as you're not the first one mentioning it, I'll work this morning on a :button: directive to take advantage of :icon: AND :guilabel:.
• inline images size is computed on the viewport width (%), to be nicely inlined it should be computed on em (size of the police) which is not possible in the .rst image directive.

let me know what you think, and we'll adapt the documentation instructions

[BuddyVolly]

hmm, that's would be a real pity imho

• I think it will definitely help for the "where" cause you are making as it is showing exactly what needs to be selected. This doesn't mean full windows get obsolete.
• image size can be computed on :height: using em, so this shouldn't be an issue either. (indeed it is much better as width)
• pdf transformation will be anyway difficult, as we use gifs (I tried make latexpdf). But if you use print statement, and export a single recipe, that's just fine. most people are anyway paperless these days.
• for the sphinx theme, I cannot say, but if it works in one css, why shouldn't it in another? maybe there is some adoption needed?

[12rambau]

Let's use democraty then !
I'll set up my thing (to at least have something to show) and then I'll create a poll

[12rambau]

A guideline must be found to maintain consistency throughout the documentation. Here is a summary of the issue: how to represent the SEPAL btn in the documentation?

option 1: use the built-in btn role

• pros:
  • it is always inline with the text (size, police, icons) as it's a pure html object and vectorized
  • easy to change if the name or icon changes (just change the text of the directive)
  • can be translated
• cons:
  • it doesn't show exactly how the button looks in the app (color exact shape)
  • the color is piloted by the sphinx theme

option 2: use inline images

• pros:
  • show the exact shape of the btn
  • we can use the em unit to align it with the text
• cons:
  • can be placed in funny way when the build is running as it's not pure html and not vectorized
  • heavy (we are adding files in an already heavy document) and more complex to change
  • cannot be translated

click on your prefered option in the poll:

[dfguerrerom]

I've voted to use the fontawesome icons mainly because I do prefer vectorized objects instead of static ones. In my repo docs I've been using images and I think that using them requires more work (crop, save, resize, link).

[12rambau]

btn role is available in the main branch and documented in the build doc: https://docs.sepal.io/en/latest/team/contribute.html#btn

[BuddyVolly]

btn role is nice, I am wondering if fore and background color can be actually set? p.s. sorry, I realize I am getting pedantic on this :)

[12rambau]

p.s. sorry, I realize I am getting pedantic on this :)

Issues are made for this no worries ;-)

btn role is nice, I am wondering if fore and background color can be actually set?

I tried but that's complicated to setup (parsing the text, find the color, make sure it make sense, what do we do if the color is not set, or the icon is not set... )

it would have looke like this: :btn: <fas fa-folder> (#000) toto with only hexadecimal colors and risk of parsing errors all over the place. Then again ther will be this dark-light theme issue (it took 6 month for Github to find a descent solution for issues' tag and I'm not as good as GitHub people....) So I prefered to keep it simpler and don't set the color in the role.