Comments (17)
@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.
from cylc-doc.
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
from cylc-doc.
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...)
from cylc-doc.
Oh, BTW, would it make sense for this issue to perhaps be moved to cylc/cylc.github.io
or cylc-admin
?
from cylc-doc.
@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.
from cylc-doc.
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 😬
from cylc-doc.
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.
from cylc-doc.
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?
from cylc-doc.
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. 😁
from cylc-doc.
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.
from cylc-doc.
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.
from cylc-doc.
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 😬
from cylc-doc.
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.
from cylc-doc.
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):
from cylc-doc.
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 agrep
1 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.)
from cylc-doc.
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.
from cylc-doc.
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).
from cylc-doc.
Related Issues (20)
- slides: re-enable slides build
- document flow-specific hold and release
- Explain Host Selection HOT 1
- optional outputs: better document how family triggers work with optional outputs
- Document meaning of inactivity timeout HOT 3
- document: cylc set HOT 3
- Request for clarification about CYLC variables for SHARE_DIR and WORK_DIR HOT 2
- add edit this page link
- Document queues better HOT 1
- Problematic overloaded "window" terminology HOT 1
- troubleshooting: diagnosing incorrect task status HOT 4
- document late event expiry
- changes: document cylc-ui#1755
- Troubleshooting Guide: Additional things to say
- task state vs status
- Make the "Use `set -euo pipefail` in Bash scripts" recommendation less ambiguous
- interventions: re-run a workflow from a specified cycle point
- Optional outputs can cause legit partially-satisfied prereqiuisites
- interventions: setting off-flow prereqs
- changes: info view
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from cylc-doc.