Skip to content
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

doc: add a cookbook #10142

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open

doc: add a cookbook #10142

wants to merge 11 commits into from

Conversation

emillon
Copy link
Collaborator

@emillon emillon commented Feb 26, 2024

This creates a "cookbook" section with some self-contained examples.

Theses examples are extracted from quick-start.rst.

One nice aspect is that these samples are linkable, and that the previous/next links work.

I tried to convert some of the examples to a style that encourages tinkering ("Run it!" / "Change it!" in hello-world for example), but most examples are just moved as is.

Questions / follow-up work:

  • in terms of diataxis, this is tutorial material. should this leave under /tutorials/cookbook?
  • the "building a hello world program from scratch" is the closest we have to a tutorial. it could be recycled into a proper one.
  • also, this tutorial is the only place we explain that the various files need to be created with a text editor and put in the same directory. this could be added to cookbook/index.
  • some recipes are not self-contained (ex: define-library), are not formatted (ex: generator), do not follow best practices (ex: c-stubs, useless (name), no :standard), or might be useless (toplevel). This can be addressed separately.
  • what about our examples directory? should it be moved to the cookbook?

@emillon emillon added the docs Documentation improvements label Feb 26, 2024
@emillon
Copy link
Collaborator Author

emillon commented Feb 26, 2024

Curious to hear your thoughts about this @ElectreAAS

Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation improvements
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant