docs/site: add "cheat sheet" overview(s) e.g. for CLI

[sadielbartholomew]

Context

It is common to find "cheat sheets", condensed summaries in a single-tab-viewable or single-page-printable format, for aspects of many medium-to-large software projects, either included under the official documentation/website, or created & distributed independently by users. Some nice & fairly diverse examples are those, as linked, for Conda & pandas (official) & for Vuex & React (unofficial).

Cylc users could benefit from something similar. They may already have created their own, or primitive or non-prettified variants of, but to minimise dissemination of misinformation, deprecated content or unsuitable practices, we could maintain (an) official "cheat sheet(s)" under version control.

If we design a print out (version), we could hand it out at appropriate training or workshops, not just as a working aid but as a material resource to promote Cylc.

NB the Rose documentation has a Cheat Sheet page including standalone Cylc aspects which is very good, but minimal in scope, only covering a basic subset of the CLI for controlling & reviewing suites. We could create a more extensive complement under the Cylc project.

Considerations

Scope

We could sensibly condense a variety of content, but what would be worthwhile? Possibilities could be common aspects of:

• CLI: especially day-to-day workflow commands. Awaiting the CLI revamp for Cylc 8 (#2972) though it could be easier &/or instructive to develop (the outline for) a CLI cheat sheet in tandem;
• APIs that are exposed to users, namely configurations: suite & global (user) configuration file sections & items, & the Python interface for the former after #1962;
• Syntax systems pivotal to such APIs: e.g. basic ISO8601 & Jinja2 constructs;
• Terminology: key items from the (prospective) glossary populated into the index page (see https://github.com/cylc/cylc/issues/2933#issue-401726973), like those listed in the bare-bones current Terminology page;
• Support: help channels & applicability of, as in the website support.html page.
• Suite run directory structure: file & sub-directories, like a condensed version of an example tree command output in the docs tutorial.

Location & format

Should any cheat sheet(s) be included under (a page within) the built Sphinx documentation, as a resource under the Cylc repo for access via GitHub, or as a resource accessible from (e.g. linked from some, or its own, page under) the Cylc website?

In the former case, we are constrained to the reStructuredText format, otherwise we can use alternative markup languages or tools (see below) which might enable a more creative solution:

create in	supply in
reStructuredText	documentation, under built Sphinx page
web (HTML, CSS, perhaps a little JavaScript)	separate root website page
LaTeX	PDF form linked & downloadable from root website page
graphics software e.g. Inkscape	image file e.g. PNG linked & downloadable from root website page

Capability for updating & reviewing content with change history rules out graphics software as a good choice, since updated images would need to be eyeballed for visual changes, lacking a traceable code diff (in the LaTeX case we could include the source code somewhere as well as the generated PDF).

Capabilities for customisation

Users have different levels of knowledge & work in different ways, so ideally we could create something that can be customised, to a sensible bare extent, to reflect that.

I envisage a one-page template into which boxes corresponding to select top-level items such as the examples listed under the above Scope section, with their own sub-categories as pluggable sub-boxes, can be dropped & dragged (to rearrange) as desired.

[kinow]

Great idea!

Scope

We could sensibly condense a variety of content, but what would be worthwhile? Possibilities could be common aspects of

I think we could have a simple one for new users, but possibly multiple cheat sheets. Each with a specific scope.

Like R does. They also invite users to contribute with translations (which I have somewhere a post-it to include a Portuguese translation someday). With time I forget dplyr, tidyr, lubridate, shiny, etc, and I never really learned ggplot2... so when I have to use R, normally I have a quick look at those cheat sheets or at some code similar to what I need to write.

Would be nice to have one for Cylc parsec (I always search within the single-page HTML CUG, but would prefer have a printed copy of the cheat sheet next to my monitor), iso8601 syntax for cylc, cylc commands, etc.

Location & format

Should any cheat sheet(s) be included under (a page within) the built Sphinx documentation, as a resource under the Cylc repo for access via GitHub, or as a resource accessible from (e.g. linked from some, or its own, page under) the Cylc website?

On location;

Maybe a single repository as R does too (e.g. https://github.com/rstudio/cheatsheets/)? Then we could have cheat sheets for cylc/cylc, but also for modules within cylc/cylc, or for cylc/cylc-web, and other repositories that may be created.

On format;

I think these cheat sheets are normally in some print-friendly format. If HTML, then we would have to make sure we have a print style sheet (which is a bit boring to create, but there may have some tool or plug-in for sphinx that we can reuse).

I envisage a one-page template into which boxes corresponding to select top-level items such as the examples listed under the above Scope section, with their own sub-categories as pluggable sub-boxes, can be dropped & dragged (to rearrange) as desired.

+1 for a 1 page template. The template from R are Powerpoints. Maybe for the ease of desining a single page to be converted to PDF with different visual elements (borders, background graphics, fonts, etc... which may take a while to design in HTML... and if we ever get Chinese and have to handle RTL in the cheat sheet generation with something like sphinx, I'm not sure if that'd be easy...)

[kinow]

Oh, BTW, would it make sense for this issue to perhaps be moved to cylc/cylc.github.io or cylc-admin?

[sadielbartholomew]

Thank you for your swift response with your thoughts, @kinow. It sounds like you have benefited from cheat sheets for other software, as have I; not everyone finds them helpful but some do immensely!

I think we could have a simple one for new users, but possibly multiple cheat sheets. Each with a specific scope.

The latter should definitely be the starting point. This will never be priority work so we can't devote much time to it, but I think we could invest in setting up a basis e.g. that example with some guidelines for extending it or creating a similar, so that users can contribute. If we are lucky, there may be some keen users who can systematise what they already have as personal help text.

On format; I think these cheat sheets are normally in some print-friendly format

Yes, I think this would be the main aim. There are some very good free poster-style templates in LaTeX that would be quick & easy to use for this purpose. Though we should consider the appearance when viewed on the monitor, as some prefer to view under a window or tab. Perhaps we should try to optimise for both views, though we could design (slightly) different versions for electronic & print.

On location; Maybe a single repository as R does
would it make sense for this issue to perhaps be moved to cylc/cylc.github.io or cylc-admin?

In my opinion, a whole repo would be unnecessary, as we do not have nearly as much content as R, & the point is to summarise information so there should not be too many files. I think the most appropriate repo to maintain this under would depend on the format chosen, however perhaps cylc/cylc was not the most appropriate choice initially. Luckily, if we want to move it across we can do so painlessly using the GitHub Beta feature 'Transfer issue'. I am not sure whether, or where, to move it yet though.

[hjoliver]

@sadielbartholomew - great idea.

I think I agree with @kinow on location though - a separate "cylc-cheat-sheet" repository would be good because we'll need several cheat sheets, that apply to several different source repos (Workflow Server, and the new UI). Repositories a pretty light weight, and easily grouped under the Cylc org on GitHub.

[kinow]

A Python machine learning researcher from NIWA akl starred this repo today, full of cheatsheets for a ML class: https://github.com/afshinea/stanford-cs-229-machine-learning. May be a good reference.

I think this issue may be moved to cylc-admin, but even if that happens, it will be probably linked in the new issue. So it should be OK commenting here, I think 😬

[sadielbartholomew]

A Python machine learning researcher from NIWA akl starred this repo today, full of cheatsheets for a ML class: https://github.com/afshinea/stanford-cs-229-machine-learning. May be a good reference.

These look nice, good spot! They are definitely clear & well-designed examples of cheat sheets made via LaTeX, but LaTeX does have many limitations (& I know some members of our team really hate it!)

What I was hoping for on the cheat sheet front is that there would be some project which includes ready-made templates which can simply be filled in as appropriate. There are some decent (though not amazing, IMO) ones for LaTeX that are easy to find via Google search e.g. here.

Even better would be some multi-format solution where the content could be set up via some configuration and then different formats could be auto-generated from that. A lot like Sphinx, but auto-generating into specialised "cheat sheet" designs for the formats. On that note, I might look into Sphinx extensions, as they may support something like that already. This might not be for a while, as this is not high priority.

[hjoliver]

They are definitely clear & well-designed examples of cheat sheets made via LaTeX, but LaTeX does have many limitations (& I know some members of our team really hate it!)

Ouch, "many limitations" is a bit harsh in my opinion. I feel the need to declare my undying love for LaTeX again ❤️ LaTeX does book-quality "typesetting", far better than any other freely available systems (particularly true if there is any math involved). And yet you can write the markup at full touch-typing speed, no matter how complex the math etc., without worrying about the layout yourself at all.
So if you want a really professional quality printable media it's very hard to do better than LaTeX. But unfortunately for LaTeX the world has gone full-web. As a compute-intensive preprocessor designed to generate a lot of layout that isn't easily displayed in browsers it doesn't do variable-layout web pages well at all. And that - for me - is why Sphinx etc. are better for generating online content (including our future cheat-sheets, no doubt) ... but the fact is, those tools are pretty unsophisticated and ugly in many ways, compared to the wondrous all-encompassing transcendent beauty that is LaTeX.

[hjoliver]

I think this issue may be moved to cylc-admin, but even if that happens, it will be probably linked in the new issue. So it should be OK commenting here, I think grimacing

I think we are intending to make a separate repository/project for cheat sheets. Maybe move the user guide there too. Or perhaps the cylc/cylc.github.io repo would be a good place for all that?

[kinow]

I think this issue may be moved to cylc-admin, but even if that happens, it will be probably linked in the new issue. So it should be OK commenting here, I think grimacing

I think we are intending to make a separate repository/project for cheat sheets. Maybe move the user guide there too. Or perhaps the cylc/cylc.github.io repo would be a good place for all that?

That could help us in having only Python issues in cylc/cylc-flow too. And the content in our docs folder when updated will have information about cylc-flow, cylc-uiserver, cylc-xtriggers, cylc-review, and so on. So +1 to move everything to another repo. This way a pull request to, e.g., "Update the documentation of cylc-xtriggers" would make more sense, than if that issue was created here in cylc-flow.

On whether under cylc.github.io or to a new repository, either way is fine for me. No strong preference on any 😬

[kinow]

I think maybe the maintainers of this ML cheat-sheet thought the same as you did @sadielbartholomew. If you look at the translations repository that they link from that main repo, the translations are several Markdown files, which appear to be the messages/text used in the cheat sheet.

I assume someone is then going through each of these, copy/paste or running some script, to produce the translated versions. I think this way contributors work only on Markdown for translation. But for new work, they still have to edit the source (which I couldn't find, but looks like LaTeX to me too).

As these cheat sheets will be quite small, I'd be OK if we used LaTeX, Pandoc, Inkscape, or any other tool that is easy to install and run. As I think it will have less modifications than the Cylc documentation, and as @hjoliver pointed, it won't generated content for a website, but instead something like a PDF.

[sadielbartholomew]

I feel the need to declare my undying love for LaTeX again heart LaTeX does book-quality "typesetting", far better than any other freely available systems (particularly true if there is any math involved).
...
So if you want a really professional quality printable media it's very hard to do better than LaTeX.

😃 🎉 you know I actually agree completely @hjoliver, I am a LaTeX fangirl myself & was trying hard here to be impartial! I did recall you had strong opinions on LaTeX but seemed to think they were unfavourable, as with a member of the UK team (not naming names). Saying that, I disagree with:

And yet you can write the markup at full touch-typing speed, no matter how complex the math etc., without worrying about the layout yourself at all.

While I love LaTeX for the customisation & styling capabilities it has & ultimately for the beauty it can produce, I personally find it time-consuming & awkward (often painful even) to actually work with: the syntax is ugly, it's really hard to debug on compilation errrors & also as a perfectionist, I have to get everything exactly as I want it, & since there is so much power from LaTeX, that is quite a curse. Not that I care much when the end product is so gorgeous, but that's how it is...

Anyway, opinions aside:

And that - for me - is why Sphinx etc. are better for generating online content (including our future cheat-sheets, no doubt) ... but the fact is, those tools are pretty unsophisticated and ugly in many ways, compared to the wondrous all-encompassing transcendent beauty that is LaTeX.

Perhaps the way forward, then, is to create some basic LaTeX cheat sheet(s) for the time being, but note to extend them in the future (post Cylc 8, I imagine) unless any users would be keen to take on the challenge? If we include the source code that compiles to the end uploaded PDF, that will enable us to keep track of changes & let people point to any incorrect content (or typos etc.) via Issue or PR.

On that note, about a year ago I started creating a "cheat sheet" type document for my own use, designed to capture key content for the MO training courses, so as per the title the scope is 'Cylc with Rose'. It's barely half-finished (& there is still some template text, hence the 🇪🇸 words), & also now out-of-date in some aspects, but as an example of style & content what would we think about something like this as a basic temporary solution to upload under cylc/cylc-cheatsheets: Cylc_with_Rose.pdf? Here's a preview of it which should be largely readable after clicking to expand to full size (so downloading the PDF shouldn't be necessary), where there is a second page to focus on the CLI (& GUIs):

[hjoliver]

@sadielbartholomew - those look really good, in terms of layout and the kind of content we might want.

BTW I wasn't actually suggesting we need to use LaTeX for cheat sheets, unless perhaps they are mainly intended to be printed out as PDF - but I imagine most people would view cheat sheets in a browser these days too (e.g. off of the cylc web site)... in which case we should probably not use LaTeX. I was merely having a good rant about newer systems not measuring up to LaTeX in terms of the quality of the finished product. But beyond that I actually I do agree with some of your criticisms.

[sadielbartholomew]

I think we are intending to make a separate repository/project for cheat sheets. Maybe move the user guide there too. Or perhaps the cylc/cylc.github.io repo would be a good place for all that?

That could help us in having only Python issues in cylc/cylc-flow too.

@hjoliver & @kinow yes, great idea & thoughts; I fully support storing the cheat sheets & also the documentation in general in separate repos.

I especially like the concept (even if it was not the original or main motivation, or even deliberate) of keeping our repositories separated by language (including markup lanaguages e.g. the RST format employed by Sphinx). That would make management easier, for example:

• we can execute (git) grep& get precise, uncluttered results (remember the annoyance of those minified JS files for the Cylc Review when a grep1 matched something inside them...);
• language-specific (e.g. style conventions, known bugs), testing can be contained largely by repo;
• new contributors who only know or want to use certain languages can easily see which components via repos to target.

We would then have (at least based on the current state of the cylc GitHub organisation):

Repo: cylc...	Language of (most) files
-flow	Python & Bash*
-ui	Vue + standard web lanaguages
-admin	Standard markdown
-uiserver	Python
-xtriggers	Python
.github.io	Standard web languages (HTML, CSS, JS)
docs (-documentation?)	RST markup (+ some Python for config)
cheat sheets (-cheatsheets?)	? (possibly LaTeX at least for now)

* I feel this raises a natural of question: should we also, with this impetus, move the test battery out of cylc-flow, since it is mainly bash?

I'll link to this comment on Riot as it a wider thought that we might want to discuss (I've wrote it here though as markdown is nicer than Riot's text message format to convey my thoughts e.g. I could use a table.)

[kinow]

I especially like the concept (even if it was not the original or main motivation, or even deliberate) of keeping our repositories separated by language (including markup lanaguages e.g. the RST format employed by Sphinx). That would make management easier, for example:

Oh, that was not intentional, but I think an interesting consequence!

we can execute (git) grep& get precise, uncluttered results (remember the annoyance of those minified JS files for the Cylc Review when a grep1 matched something inside them...);

+1, even in an IDE it's way easier with less files/languages/frameworks/etc.

• I feel this raises a natural of question: should we also, with this impetus, move the test battery out of cylc-flow, since it is mainly bash?

I think the test-battery is now becoming a utility that is included in the cylc-flow repository, but it is not a part of the cylc-flow final project. i.e. when the user installs pip install cylc-flow, it won't even be downloaded by pip.

I'm OK with it residing with cylc-flow for now. My rationale for that is that this is a utility used solely by Cylc developers to run functional tests for Cylc. Fixes and bugs in the test-battery code are probably related to changes in Cylc, so we can see the change to cylc-flow Python code, with its accompanying changes to functional tests - if any.

If we had two repositories, and did a large change like the recent one for CYLC_DIR, that would be much harder with two repositories to update, IMO. This could change later, as we could find other ways to organise the tests or the code... but for now I'm OK with the test-battery residing withing cylc-flow.

Now, the profile-battery for me could go to its own repo. It's a separate utility, which changes to its code shouldn't affect Cylc, and vice-versa.

[sadielbartholomew]

If we had two repositories, and did a large change like the recent one for CYLC_DIR, that would be much harder with two repositories to update, IMO. This could change later, as we could find other ways to organise the tests or the code... but for now I'm OK with the test-battery residing withing cylc-flow.

Ah, yes, that's a very good point, @kinow. In which case, the set-up plan you mention for the tests:

I think the test-battery is now becoming a utility that is included in the cylc-flow repository, but it is not a part of the cylc-flow final project. i.e. when the user installs pip install cylc-flow, it won't even be downloaded by pip.

sounds ideal to me. Maybe RE the test battery I got a bit carried away on segregating further by language without thinking much about the consequences...

I'm now wondering how we ensure the documentation is kept up-to-date on a PR-by-PR basis (for changes which mean the docs needs modifying or adding to), if it is put in another repo. Perhaps we can add an item to the list on the PR template? Something like this:

COMMENT: choose one & fill in the PR ID XXXX in the former case:
- [ ] I have opened a PR to <docs repo name> (#XXXX) with corresponding amendments
      or extensions  (as appropriate) to the documentation.
- [ ] No documentation change required (change non-documentable & does not contradict
      current docs content).

[kinow]

Oh, hadn't thought about using the template to help with documentation, but I think that's a good idea. we may need to set up templates in other projects that may use the centralized documentation repo (e.g. cylc-uiserver, cylc-ui, future cylc-review, etc). +1

[hjoliver]

Excellent ideas. I agree, the docs should become a separate project because they (unlike the test battery) will apply to use of all cylc components. And prompting for documentation updates in the PR template is good. 😁