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

src/lib/ should be better documented #733

Closed
wingo opened this Issue Feb 2, 2016 · 11 comments

Comments

Projects
None yet
4 participants
@wingo
Contributor

wingo commented Feb 2, 2016

This issue has a few parts. I start with a summary.

One, src/lib/ is largely undocumented. That's OK, we can document.

However, it's hard to fit documentation for src/lib/ modules into the main document. One reason is that https://github.com/SnabbCo/snabbswitch/blob/master/src/README.md documents src/core/lib, which is a bit confusing. I don't know how to explain this properly, that there is core.lib which has e.g. lib.htons but there is also lib.ctable, but that's a module. I think the name "lib" is being used too much. Perhaps that is a Snabb design problem rather than a documentation problem per se; thoughts, @lukego?

Another problem is that https://github.com/SnabbCo/snabbswitch/blob/master/src/doc/genbook.sh#L54 isn't able to document individual files in src/lib/, because of #722 (comment). Basically, the design right now is to always only include README.md files, but we can't have a src/lib/README.md because the main book already pulls in parts of src/lib/*/README.md, and it would be hard to describe all of src/lib in one section otherwise. But describing all of the modules in src/lib/README.md isn't so nice either, because the file could get really long. I propose that we allow src/lib/README.foo.md, where foo indicates the module name. That way we still allow separate documentation files while not forcing all modules to be in subdirectories and preserving the ability of genbook to section the main document however it likes. Thoughts, @eugeneia ? I would normally be happy to deal with this in #722 but Luke suggested I open an issue. Sorry for the conversation duplication :)

@lukego

This comment has been minimized.

Show comment
Hide comment
@lukego

lukego Feb 2, 2016

Member

I really need a good way to consume documentation. How do other people do it?

I really enjoy having everything on Github when I want to send a link to it e.g. on the mailing list. However, I don't browse documentation on Github: I find it very laggy and the search too limited.

Currently I am most often digging up documentation in a text editor but this is not optimal when I have to open a separate readme file and read in markdown syntax.

Member

lukego commented Feb 2, 2016

I really need a good way to consume documentation. How do other people do it?

I really enjoy having everything on Github when I want to send a link to it e.g. on the mailing list. However, I don't browse documentation on Github: I find it very laggy and the search too limited.

Currently I am most often digging up documentation in a text editor but this is not optimal when I have to open a separate readme file and read in markdown syntax.

@bradjonesca

This comment has been minimized.

Show comment
Hide comment
@bradjonesca

bradjonesca Feb 2, 2016

Naive suggestion here, Algolia's free "Hacker" package? https://www.algolia.com/pricing

bradjonesca commented Feb 2, 2016

Naive suggestion here, Algolia's free "Hacker" package? https://www.algolia.com/pricing

@eugeneia

This comment has been minimized.

Show comment
Hide comment
@eugeneia

eugeneia Feb 2, 2016

Member

Regarding reading documentation: I have briefly experimented with GitBook and readthedocs.org the other day and failed to make them read Snabb Switch documentation, e.g. I lost patience while trying to debug why they couldn't import our Markdown files. I had this experiment with hosting pre-compiled html versions of our genbook.sh at a canonical place a year (or so) ago but forgot about that as I felt there was no demand. I would suggest this approach again though, make doc/snabbswitch.html should still work (and the dependencies are documented in doc/README.md). Its easy to optimize the CSS for API referencing and its single page e.g. C-f works (is more sophisticated searching of interest?).

Member

eugeneia commented Feb 2, 2016

Regarding reading documentation: I have briefly experimented with GitBook and readthedocs.org the other day and failed to make them read Snabb Switch documentation, e.g. I lost patience while trying to debug why they couldn't import our Markdown files. I had this experiment with hosting pre-compiled html versions of our genbook.sh at a canonical place a year (or so) ago but forgot about that as I felt there was no demand. I would suggest this approach again though, make doc/snabbswitch.html should still work (and the dependencies are documented in doc/README.md). Its easy to optimize the CSS for API referencing and its single page e.g. C-f works (is more sophisticated searching of interest?).

@eugeneia eugeneia added the bug label Feb 3, 2016

@lukego

This comment has been minimized.

Show comment
Hide comment
@lukego

lukego Feb 4, 2016

Member

Having an up-to-date easy-to-find single-file manual sounds fantastic to me.

Ideally this would be built by the CI and trivially easy to refer to so that it is obvious to everybody whether their new change is keeping the documentation consistent or not. Could SnabbBot perhaps make doc/snabbswitch.html and post the result on the Gist?

I think that the best thing we can do for documentation quality is to attract people to actually use it on a daily basis. I will make it a personal goal to start doing this and see what is necessary to make it stick :).

Member

lukego commented Feb 4, 2016

Having an up-to-date easy-to-find single-file manual sounds fantastic to me.

Ideally this would be built by the CI and trivially easy to refer to so that it is obvious to everybody whether their new change is keeping the documentation consistent or not. Could SnabbBot perhaps make doc/snabbswitch.html and post the result on the Gist?

I think that the best thing we can do for documentation quality is to attract people to actually use it on a daily basis. I will make it a personal goal to start doing this and see what is necessary to make it stick :).

@wingo

This comment has been minimized.

Show comment
Hide comment
@wingo

wingo Feb 4, 2016

Contributor

Are we OK in the long term with the existence of both core.lib module and the lib module tree? If no one else finds this confusing, I will ignore it :)

Contributor

wingo commented Feb 4, 2016

Are we OK in the long term with the existence of both core.lib module and the lib module tree? If no one else finds this confusing, I will ignore it :)

@lukego

This comment has been minimized.

Show comment
Hide comment
@lukego

lukego Feb 4, 2016

Member

Are we OK in the long term with the existence of both core.lib module and the lib module tree?

I hope that with #734 we can present our API to application developers in a coherent way that is independent of the source code layout and Lua module names.

Then the issue of lib vs core.lib would at least be less significant i.e. we would be talking about the internal factoring of the implementation.

I have an overall sense that our API is too big. We have originally written code quite freely, with all functions externally visible from all modules, and then we have documented the result. The step we are missing is "recoil in horror at the haphazard API and revise, revise, revise." You may already be onto that step @wingo but I am not quite there yet... I don't immediately have access to an update-to-date copy of the documentation (getting one requires connecting to a suitable development host, installing the necessary dependencies, building the HTML manual, copying it somewhere that my browser can find it. I already did that this morning but on another machine :).)

Member

lukego commented Feb 4, 2016

Are we OK in the long term with the existence of both core.lib module and the lib module tree?

I hope that with #734 we can present our API to application developers in a coherent way that is independent of the source code layout and Lua module names.

Then the issue of lib vs core.lib would at least be less significant i.e. we would be talking about the internal factoring of the implementation.

I have an overall sense that our API is too big. We have originally written code quite freely, with all functions externally visible from all modules, and then we have documented the result. The step we are missing is "recoil in horror at the haphazard API and revise, revise, revise." You may already be onto that step @wingo but I am not quite there yet... I don't immediately have access to an update-to-date copy of the documentation (getting one requires connecting to a suitable development host, installing the necessary dependencies, building the HTML manual, copying it somewhere that my browser can find it. I already did that this morning but on another machine :).)

@lukego

This comment has been minimized.

Show comment
Hide comment
@lukego

lukego Feb 4, 2016

Member

btw there are some handy Git tricks for making it easy to checkout/merge/diff PR branches from your working copy. Here's a link to my favorite but you can also do a one-liner version without any config e.g. git fetch origin pr/nnn/head && git merge --no-ff FETCH_HEAD.

Member

lukego commented Feb 4, 2016

btw there are some handy Git tricks for making it easy to checkout/merge/diff PR branches from your working copy. Here's a link to my favorite but you can also do a one-liner version without any config e.g. git fetch origin pr/nnn/head && git merge --no-ff FETCH_HEAD.

@lukego

This comment has been minimized.

Show comment
Hide comment
@lukego

lukego Feb 4, 2016

Member

(Comment above was meant for #737.)

Member

lukego commented Feb 4, 2016

(Comment above was meant for #737.)

@eugeneia

This comment has been minimized.

Show comment
Hide comment
@eugeneia

eugeneia Feb 9, 2016

Member

Could SnabbBot perhaps make doc/snabbswitch.html and post the result on the Gist?

Yes, but for that I request a solid address I can serve HTTP from, e.g. docs.snabb.co. I don't want to do the “documentation is at lab1.snabb.co:2008/~max/...” dance again. :)

Member

eugeneia commented Feb 9, 2016

Could SnabbBot perhaps make doc/snabbswitch.html and post the result on the Gist?

Yes, but for that I request a solid address I can serve HTTP from, e.g. docs.snabb.co. I don't want to do the “documentation is at lab1.snabb.co:2008/~max/...” dance again. :)

@lukego

This comment has been minimized.

Show comment
Hide comment
@lukego

lukego Feb 10, 2016

Member

@eugeneia I see two different use cases here for making the docs accessible:

  1. Make the documentation for the latest release available at a canonical URL.
  2. Make the documentation for each feature branch available during review.

The first one seems reasonable to solve with a file in a well-known location. Could perhaps host the full snabbswitch.html and snabbswitch.md in its own Github Pages repo? Then we could also use the Github interface to view diffs in the markdown between releases which might be convenient.

How about the second one? The best idea I have is for SnabbBot to make doc/snabbswitch.html and store the result as an attachment file on the Gist where it posts its results.

This is something we could also in principle farm out to a Hydra server. They have the notion that every build generates well-defined artifacts (tarball, manual, test logs, etc) that are archived and served up. For example: build with code coverage report and build with release tarball. Hydra might be a viable way to avoid excessive feature-creep in SnabbBot.

Member

lukego commented Feb 10, 2016

@eugeneia I see two different use cases here for making the docs accessible:

  1. Make the documentation for the latest release available at a canonical URL.
  2. Make the documentation for each feature branch available during review.

The first one seems reasonable to solve with a file in a well-known location. Could perhaps host the full snabbswitch.html and snabbswitch.md in its own Github Pages repo? Then we could also use the Github interface to view diffs in the markdown between releases which might be convenient.

How about the second one? The best idea I have is for SnabbBot to make doc/snabbswitch.html and store the result as an attachment file on the Gist where it posts its results.

This is something we could also in principle farm out to a Hydra server. They have the notion that every build generates well-defined artifacts (tarball, manual, test logs, etc) that are archived and served up. For example: build with code coverage report and build with release tarball. Hydra might be a viable way to avoid excessive feature-creep in SnabbBot.

@eugeneia

This comment has been minimized.

Show comment
Hide comment
@eugeneia

eugeneia Mar 14, 2016

Member

I am closing this because it is (being) solved in #824 #805 #790

Member

eugeneia commented Mar 14, 2016

I am closing this because it is (being) solved in #824 #805 #790

@eugeneia eugeneia closed this Mar 14, 2016

dpino pushed a commit to dpino/snabb that referenced this issue Feb 14, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment