Project documentation website #1017
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ti-mo
force-pushed
the
tb/docs
branch
4 times, most recently
from
102c907
to
e605539
Compare
ti-mo
force-pushed
the
tb/docs
branch
2 times, most recently
from
bf6adae
to
f4b500d
Compare
ti-mo
force-pushed
the
tb/docs
branch
5 times, most recently
from
24b997a
to
23ba515
Compare
lmb
approved these changes
Sep 25, 2023
There was a problem hiding this comment.
This is great, and we should push it ASAP. Like I mentioned on our call, my main concern is that we nail down what kind of person we write for. As an example, some of the concepts pages explain both really basic Go things and "super advanced" finalizer stuff. I think that this makes the content less useful to both the less and the more advanced readers. In the best case we can build a "ladder" where our typical reader comes in and can go from basic to ever more complex pages.
I'd prefer if we'd start by writing for someone like this:
- A good grasp of the Go language, with an understanding of best practises. Able to write idiomatic Go. To me that implies being able to deal with os resources: read a file, open a socket.
- A basic grasp of C. Did some coding in uni or wherever. No need to explain the syntax of a function call or arithmetic.
- Prior knowledge of ebpf.io/what-is-ebpf.
- No knowledge of Go runtime internals.
- No knowledge of Linux kernel internals.
- No knowledge of C compiler specifics like magic macros, attributes, etc.
The first step in the ladder would be to get that person productive when using the lib. The second step would be to get that person ready to contribute.
ti-mo
force-pushed
the
tb/docs
branch
10 times, most recently
from
2dce778
to
8c84560
Compare
Signed-off-by: Timo Beckers <timo@isovalent.com>
Explained in comments. Minimal impact to existing .c code, but makes rendered code blocks in markdown easier to read. Signed-off-by: Timo Beckers <timo@isovalent.com>
This allows docs and examples to depend on <bpf/bpf_helpers.h> and friends, reducing the amount of actions needed for newcomers to get up and running. Signed-off-by: Timo Beckers <timo@isovalent.com>
As of Go 1.21: go build ./... seems to build all main subpackages discarding output binaries. go test -c -o /dev/null also works as expected. Signed-off-by: Timo Beckers <timo@isovalent.com>
This commit introduces an mkdocs-based documentation boilerplate, containing: - The mkdocs configuration (mkdocs.yml), defining the site's navigation and ToC - Python dependency management using pipenv - Netlify configuration for automated builds & deploys - eBee emoji - Macros for easily including real code examples into documentation. These examples get built in CI, ensuring they don't rot when API or dependencies change. - A glossary for commonly-used terms in BPF land. - Custom admonition for rendering warnings about incomplete documentation sections using '!!! incomplete'. Signed-off-by: Timo Beckers <timo@isovalent.com>
Signed-off-by: Timo Beckers <timo@isovalent.com>
This patch adds deep-dives on ELF loading, object lifecycle, resource limits and ELF section naming. Illustrated by a few C and Go examples. Add a note to elf_reader.go to keep the ELF section prefix table up to date. Signed-off-by: Timo Beckers <timo@isovalent.com>
We want to write about bpf2go, BTF, feature probing, and working with maps and programs. Add a few writing prompts to help prospective authors to get started. Signed-off-by: Timo Beckers <timo@isovalent.com>
Signed-off-by: Timo Beckers <timo@isovalent.com>
This patch includes an override of a partial that supports hiding the title to create a nicer-looking landing page. Otherwise, mkdocs-material always renders an <h1> if we specify a custom <p> for a tagline graphic. Signed-off-by: Timo Beckers <timo@isovalent.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.