[OSGeoLive] Quick starts status update (Google Season of Docs)

Seth G sethg at geographika.co.uk
Mon Oct 7 07:34:16 PDT 2019

Hi Felicity,

With regards to the Sphinx markup, using the directives would have the following advantages:

- allow a consistent way to show menu selections (or any conventions such as File > Open, File -> Open, File | Open could be used. It is probably simplest to stay with the Sphinx convention rather than create a new one. 
- allow a theme to be applied across all the docs in the future e.g. the GUI labels at https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#inline-markup
- shortcut keys can be applied to the labels e.g. button :guilabel:`&Start`

It may also help with translating and matching GUI labels in different languages. 

If they are already widely used I'd be in favour of keeping them  and applying elsewhere. 


twitter: @geographika

On Mon, Oct 7, 2019, at 6:56 AM, Felicity Brand wrote:
> Hello all,
> I've been working on the Quick Start template and there are a couple
> of questions I wanted to ask.
> I have come across the Sphinx markup :guilabel: and :menuselection:
> What do we gain by using these? It seems to me something extra to
> type. I understand we can then render them a particular way, but if
> it's just going to be rendered bold it feels like more effort than
> it's worth. But please let me know if I'm missing something in my
> understanding here. Do we want to continue using this convention?
> I'd like some guidance on my process next.
> At a previous meeting, we agreed that the best way for me to give
> feedback would be GitHub comments. I think I need to raise a PR in
> order to be able to comment on the code. But I didn't intend on making
> any changes...so I'm not sure what would go in my PR. Unless I make
> some kind of nominal change that we all agree on beforehand? I suppose
> we'll want a PR per project quick start - so that would be maybe 50
> PRs. Is that cool with everyone?
> My intention was to also create about 50 trac tickets, one for each
> project. These would include the details of my rating score of the
> quick start and perhaps a link to the relevant GitHub PR. I thought it
> would be appropriate to have trac as well as GitHub so that anyone
> could look at the trac ticket and pick up from there. What do folk
> think about that?
> I'm not ready to start any GitHub work yet, but I wanted to get
> discussion on this rolling so that I know what to do when that time
> comes.
> Thanks
> Felicity
> _______________________________________________
> osgeolive mailing list
> osgeolive at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/osgeolive

More information about the osgeolive mailing list