Sphinx docs

[Wenzel]

This PR adds a Sphinx based documentation

2 new make user targets:

• docs: build the HTML docs
• open_docs: ensure the docs are built and opens the documentation using xdg-open

[il-steffen]

I think make open_docs this won't work on Windows remote terminal or when the server has no X utils. For the user, the README frontpage should just refer to the github pages instead?

With that change, I don't know if we need the open_docs recipe. But keep it if you like :-)

[Wenzel]

I think make open_docs this won't work on Windows remote terminal

On Windows you don't have make by default, so kafl's dev environment is not targeting Windows users anyway.

when the server has no X utils

🎉

yes xdg-open can find the necessary tools to open an HTML page in an ncurses interface

For the user, the README frontpage should just refer to the github pages instead?

For the end user, the documentation will be accessible on Github Pages, and there will be a README Badge pointing it, as well as the project website link:

[il-steffen]

I know how it works, just saying that it may not exist on a server install. We probably have to add xdg-utils to dependencies. Its a freedesktop thing and probably pulled in with some basic desktop utils (not necessarily a full X/wayland install).

For Windows, I meant when using Windows ssh to remote server. I guess ssh will have no X forwarding and so xdg-open will just use the terminal browser, if available..

While this is nice and fun, I'm just doubting the relevance to the user here :-) They are probably better served with the public webpage link. For development the steps are quite clear. A local generated or downloadable pdf may be useful for corner cases..

[Wenzel]

I know how it works, just saying that it may not exist on a server install

On a server install I assume you are running kAFL, not developing.

For Windows, I meant when using Windows ssh to remote server

The docs are not meant to be displayed over an SSH connection, but on your local box.

While this is nice and fun, I'm just doubting the relevance to the user here :-) They are probably better served with the public webpage link. For development the steps are quite clear.

The relevance would be to develop your own PR and update the documentation. Having a top-level targets that simplifies these steps is always welcomed I believe.

I understand your point, and I can remove the open_docs rule which is just an extra.

[il-steffen]

OK, so it is meant as a shortcut for developer use. The README section confused me, hence my comment to maybe just point to webpage there.

For local dev use, I'm fine with adding the shortcut. It seems a bit overkill, I will probably never remember that but just open the html manually and press ctrl-R. :-)

Maybe make all should just print a command help, then.