Improving sljit's documentation

[ningvin]

I have been using sljit for some time now and am quite happy with it :-)

One thing where I see room for improvement though is its documentation. There are currently 4 places where documentation can be found (apart from the code itself):

• The top-level README
• The overview in doc/overview.txt
• The website
• The tutorial in doc/tutorial, which can AFAIK only be viewed on external pages like this one

This makes it both hard for newcomers to find their way around, as well as contributors to keep the different sources up to date and in sync.

I would like to help out and improve the documentation, but wanted to check with you first before putting time into a pull request. The reason being that I see roughly two ways to go about this:

1. Keep the general structure as is (i.e. a separate website in the gh-pages branch, as well as documentation in the master branch) and only clean up / add some stuff
2. Use a documentation / static site generator, e.g. docusaurus which seems to be (one of?) the most popular ones

I would suggest the latter strategy, as this would allow writing all the documentation in Markdown in one place and deploy it automatically via some GitHub workflows magic.

Let me know what you think :-)

[zherczeg]

Thank you for the help. I always wanted to be things simple, so the sljit documentation is in https://github.com/zherczeg/sljit/blob/master/sljit_src/sljitLir.h

The readme and the website is just some general overview, and not intended to be a documentation. It could be, but I have no resources to do it.

The doc directory is contributed by others, I have never touched anything there. So if you want to improve things there, feel free to do it. Probably lots of things are outdated there. If you want to add / replace things with static html pages, I am ok with it.

@carenas or @invertego who cotributed to doc/ might be also interested in your changes.

[ningvin]

Thanks for the quick reply!

I always wanted to be things simple, so the sljit documentation is in https://github.com/zherczeg/sljit/blob/master/sljit_src/sljitLir.h

I have been a bit unclear in my usage of the word "documentation". sljitLir.h would still stay the ultimate truth, I would only consolidate + update the existing additional resources (like the README, the tutorial, ...).

The readme and the website is just some general overview, and not intended to be a documentation. It could be, but I have no resources to do it.
The doc directory is contributed by others, I have never touched anything there. So if you want to improve things there, feel free to do it. Probably lots of things are outdated there. If you want to add / replace things with static html pages, I am ok with it.

Just to clarify: does that mean a static documentation site generator would be an option for you? The structure could look like this (going with docusaurus here as it is the one I know best; would be surprised though if the others use a drastically different approach):

sljit
├── .github/workflows
│   ├── actions.yml
│   └── deploy-website.yml # automatically deploy website on pull into master
├── regex_src
├── sljit_src
├── test_src
├── website # embedded docusarus site
│   ├── docs # existing / revamped documentation in markdown
│   │   ├── overview.md
│   │   ├── supported-platforms.md
│   │   └── ...
│   ├── src # some scaffolding for the home page
│   ├── ...
│   └── package.json # docusaurus dependencies (can be ignored by most users / developers)
├── ...
└── README

Documentation / examples / tutorials could then be simply written as markdown and deployed automatically on pull. Users / developers of sljit would not need to worry about the website details and could ignore the NodeJs project most of the time.

In case you would rather keep things separated as they are now (website as static html in gh-pages branch, documentation in doc folder), I would still suggest that the contents of the doc folder be written in markdown instead of static html. It's just easier to write and renders way nicer on GitHub.

I would not mind either way, so let me know what you prefer (or if you have something different in mind) :-)

[zherczeg]

I like markdown, and in fact I prefer it over html. Easier to maintain, and I think github can nicely display it.

I would keep the docs subdirectory though:

+ docs
  + *.md
  + more subdirectories such as api 
    + *.md
  + website
    + src (of generator)
    + out (generates the static html pages here, not part of the repository)

The generated html pages could be manually copied into the gh-pages branch.

[carenas]

Documentation / examples / tutorials could then be simply written as markdown and deployed automatically on pull.

one useful "feature" of the current state is that the examples are valid C code (which can be tweaked) and can be built by invoking make examples.

the fact that the contents of those files are duplicated is bad though, but if you are going to generate a "website" then it will be better to keep them AS-IS (maybe adding comments) and process them to generate the expected output IMHO.

[ningvin]

one useful "feature" of the current state is that the examples are valid C code (which can be tweaked) and can be built by invoking make examples.

Good point, I almost forgot about that make target.

the fct that the contents of those files are duplicated is bad though, but if you are going to generate a "website" then it will be better to keep them AS-IS (maybe adding comments) and process them to generate the expected output IMHO.

That should absolutely be possible with the framework, I will look into it. If time permits I hope I have something to show by the end of next week, but no promises 🙃