Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs #13

Open
marcin-rzeznicki opened this issue Jul 6, 2017 · 3 comments
Open

Improve docs #13

marcin-rzeznicki opened this issue Jul 6, 2017 · 3 comments

Comments

@marcin-rzeznicki
Copy link
Contributor

marcin-rzeznicki commented Jul 6, 2017

There are several things that the documentation is currently missing and could be helpful to future contributors:

  • Explain code organization
  • How to test your code
  • How to debug
  • ...

It can be added in form of CONTRIBUTING guide

@luksow
Copy link
Contributor

luksow commented Apr 5, 2018

Some new features are still not described.

Also it'd be good to have a docs page beside README.

@rpiotrow
Copy link
Contributor

README mentions CaseClass1Rep which is not explained (and it is specific for kebs). IMHO, it should be described and explained how it is used in kebs.

@rpiotrow
Copy link
Contributor

If we would like to use GitHub Pages for it, we can use:

  • mdoc - that can process markdown files into markdown files, benefits:
    • it has ability to compile sample code scala
    • checks internal links
    • it support some kind of variables (e.g. we can "inject" value of current version of the library)
  • for creating site from markdown (either "raw" one or output from mdoc) we can use:
    • jekyll
      • default mechanism of GitHub Pages, pretty old, but looks mature
    • docusaurus
      • downside: for what is see it has only option to creates website on a separate branch (gh-pages)
      • upside: mdoc suggested library
      • upside: modern stack

Probably we will need to move documentation from the README.md in the root directory into some structure of files. Current README can contain some overal description with list of features - which will link to the documentation on the GitHub pages.

I would suggest to try mdoc and jekyll and see how it looks. We can create fork of the repo and experiment there to not litter main repo, what do you think?

This was referenced Sep 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants