search

codewars / docs

The Codewars Docs :construction: WIP
https://docs.codewars.com
MIT License
56 stars 194 forks source link

Define format of language reference page #65

Open hobovsky opened 4 years ago

hobovsky commented 4 years ago

Currenlty pages describing a language supported by Codewars are quite comprehensive, but I think they could be both standardized and a bit richer. I thought about including following information:

✔️ - already is there ⚠️ - is there, but could be improved ❌ - is not there, IMO important ❓ - could be useful, but not sure

  1. language slug/id used in code blocks and url routes ⚠️ (it;s already there, but not labelled, so I did not even know that what I am looking at is language ID)
  2. available runtimes and versions ✔️
  3. Timeout ✔️
  4. Test frameworks ⚠️ it's already there, but often is missing a version, and it could use a link to the framework reference or something
  5. Available packages ✔️
  6. Command line used for compilation and running ❌
  7. How solution is prepared, built and run: files are concatenated, put in some module, etc. ❌
  8. Some interesting details like path to solution file if tests would like to read it ❓
  9. Icon used by Codewars ❌
  10. Link to CW docs, tutorials and howtos related to the language: authoring translation into this language, creating tests in this language (they will be appropriately tagged, so maybe it's not needed?) ❓
  11. Notes on frequently encountered issues or problems (can;t think of anything specific ATM, but I believe there are some) ❓

What do you think? What else would you add?

Blind4Basics commented 4 years ago

Some points might become redundant with tutorials about writing tests in that language (8 & 11 especially), so maybe just the link to the related page could be enough for those.

6) noob question: what's the interest, here? (in context of cw). I mean... other than having more guys like unnamed running interpreters from the guts of their solutions...? XD

hobovsky commented 4 years ago

I can think of a couple of specific scenarios it would be helpful:

Another benefit (?) would be that more details about runtime would be known, potentially making it easier to create some highly hermetic kata related to language internals, but it was not my initial intention behind this suggestion.

Blind4Basics commented 4 years ago

(I definitely don't do enough low language stuff... XD )

:+1:

kazk commented 4 years ago

4. Test frameworks :warning: it's already there, but often is missing a version, and it could use a link to the framework reference or something

The version depends on the language version so I was going to include them in packages. Link to the website can be added and our docs will be listed in the sidebar.

6. Command line used for compilation and running

I'll add flags field.

7. How solution is prepared, built and run: files are concatenated, put in some module, etc.

:+1:

8. Some interesting details like path to solution file if tests would like to read it

This needs a dedicated page. It's always at /workspace/solution.txt for any language. Older language versions have /home/codewarrior symlinked to /workspace so /home/codewarrior/solution.txt works on those, but should be updated to /workspace/solution.txt.

9. Icon used by Codewars

I don't think it's that important, but nice to have. I should create a new repository for the language icons.

10. Link to CW docs, tutorials and howtos related to the language 11. Notes on frequently encountered issues or problems

Just include the language in languages field and it'll show up on the sidebar.

  • paths used by compiler and solution: working dir, solution file name (basically pt 8)
    I believe there are many more interesting things to find there in current setup, for various languages.

I'm not going to document minor details because I wouldn't want kata tightly coupled with the current environment. I'll consider exposing some information in some general form (like environment variables) if the authors find them useful.