clio icon indicating copy to clipboard operation
clio copied to clipboard

Published 20 hours ago • verified publisher icon clio-lang

Update documentation

Open garritfra opened this issue 5 years ago • 9 comments

As discussed below, we need at least a language reference before we release the next version of Clio. We can use The Rust Book and The Swift Language Guide as a reference (pun intended).

Criteria

  • [ ] The import system is documented (#66, #72, #67)
  • [ ] Keywords are documented
  • [ ] Data types are documented
  • [ ] Expressions are documented (functions, conditionals, ranges...)
  • [ ] Function decorators are documented
  • [ ] Features of the new CLI are documented
  • [ ] TOML fields are documented

Room for Discussion

  • Should we switch from GitBook to mdBook?

garritfra avatar Apr 08 '19 17:04 garritfra

At the minimum a language reference is needed. It's not useable without it.

mationai avatar Apr 28 '19 11:04 mationai

You are correct. Documentation should be a crucial part in the development process. Clio is still in its early stages, the syntax of the language is therefore still subject to change. It's a thing we want to work on improving. Please feel free to help us out!

garritfra avatar Apr 28 '19 11:04 garritfra

There are a few changes in the way the language works, I'm working on them, as soon as it's finished I'm going to do a better documentation. I cannot do a language reference right now because the syntax and the features aren't stable now.

pouya-eghbali avatar Apr 28 '19 17:04 pouya-eghbali

The current documentation generator we use isn't free anymore, but I still find it the nicest. I believe there's still a free version, however I don't know what kind of limitation there is for free members.

pouya-eghbali avatar Dec 19 '19 06:12 pouya-eghbali

Gitbook? If all hell breaks loose, we can use a static site generator like Gatsby

garritfra avatar Dec 19 '19 07:12 garritfra

Take a look at this

garritfra avatar Dec 19 '19 07:12 garritfra

Does this still need work on? I haven't done documentation before but would like to contribute if I can get a little guidance on what needs to be added.

dkbearsong avatar Aug 21 '20 16:08 dkbearsong

Hi @dkbearsong!

We can always use help with documentation. I'd suggest you take a look at the documentation, and if something is puzzling you, ask us in our telegram group and open a pull request! :) the bullet points above could also give you a hint on what's missing.

Thanks for your help!!

garritfra avatar Aug 21 '20 16:08 garritfra

Interested to translate to more than one language? I can do the Brazilian Portuguese version of doc.

RigottiG avatar Mar 18 '21 21:03 RigottiG