Initial Snabb Switch Reference Manual

[eugeneia]

I am admittedly a tiny bit proud to present to you.... a fairly complete Snabb Switch Reference Manual!

By "fairly complete" I mean most parts of the Snabb Switch distribution are documented, and it should already be a useful resource for Snabb Switch hackers, old and new.

What's still missing:

• I did not document the ipv6.ipv6 app. It looks like a stub/example to me? Uses none of the protocol libraries and as far as I can tell it mostly responds to pings. Not sure.
• Not all libraries (src/lib) are documented yet. If you think a specific library should be in the documentation, let me know!
• I probably forgot something: You can either add it yourself or tell me to do it.
• Proof reading is highly appreciated! Don't attempt to read the whole thing at once please, might be dry. ;)

Merry Christmas!

[plajjan]

"repeatedly by the" .. engine?

[plajjan]

I read it all at once... massive. Nice work! Answers a lot of stuff I had to find out the hard way. I'll read again but regardless I vote for merge as it's lightyears better than the current situation. Can always fix/add more later on.

BTW, have you considered something like readthedocs.org or gitbook.io for keeping a fairly good-looking document up to date with latest git repo?

[eugeneia]

Thanks for the proof-read, I didn't expect so much valuable feedback so fast! =) As for your suggestions: Yes to all cases! 👍

BTW, have you considered something like readthedocs.org or gitbook.io for keeping a fairly good-looking document up to date with latest git repo?

We could let SnabbBot render the current documentation automatically. I don't consider that very important though, because if the docs change too often (besides stylistic fixes and new additions) that would be a bad sign since they are written as a contract for the user. So including rendered versions with the releases seems good enough to me for now.

Regarding other doc tools: I am actually quite fond of our tool chain. The docs automatically embed into GitHub (albeit, ToC rendering would be nice). They are managed just like any other source file so it should be easy to keep them up to date with the code. And then we heavily use a Ditaa pre-processing step to be able to easily embed graphics using a funny ASCII syntax (its a bit buggy but generally fun to work with).