make the doc's technical content dynamic

[cjdcordeiro]

At the moment, we have a tutorial https://github.com/canonical/rockcraft/blob/main/docs/tutorials.rst with a technical example of a rockcraft.yaml file which is not only being maintained manually but not tested anywhere in the CI pipelines.

Examples and tutorials should be tested.

Proposal

Make the technical contents of the documentation dynamic, by fetching the respective blocks of code from the project's test folder. Example: docs/tutorials.rst should use tests/spread/tutorials/basic/, where the actual tutorial YAML and tasks are described, and tested by Spread during the CI.

[SamirPS]

Hello, I am beginning to solve this issue, but for the task.yml. I use includefile with start-line, so if the line for the rockcraft pack changes to line 3 to 5 it's will not be shown on the documentation. It's a problem or not ? @cjdcordeiro

[cjdcordeiro]

Hello, I am beginning to solve this issue, but for the task.yml. I use includefile with start-line, so if the line for the rockcraft pack changes to line 3 to 5 it's will not be shown on the documentation. It's a problem ?

hi.

yes, that could be a problem. ideally, we shouldn't make any assumptions on the content of these files, except for their syntax. i.e. task.yml must have the summary and execute attributes. that's all we know.

[SamirPS]

Hi,

okay, but do you want to display all the execute and nothing else for the step or you want to add some sentence in the rst for each step of execute ?

[cjdcordeiro]

well that's a good question.

It feels like we need some sort of convention here. So this issue cannot be addressed without proper discussion first.

There are many easy implementations (for example, we could use ## signs in task.yml to represent raw text that is supposed to be included in the docs. But maybe a more elegant solution will arise once we think a bit more about this

[SamirPS]

when you says ## you tell for example if i have this file :

test.yaml

summary: smoke test for the retry tool

execute: |
  ## Do a ls 
  ls

you want to display like that :

Do a ls

ls

Or like that :

Do a ls:
ls

The second option is easy, the first one idk

[cjdcordeiro]

more like the 1st one. but that was just an idea. TBD

[sergiusens]

I took note on this and wondered if we could do the reverse. I am looking at the literate programming options available in the sphinx/rst world.

On Fri, Aug 19, 2022 at 9:48 AM Cristovao Cordeiro @.***> wrote:

more like the 1st one. but that was just an idea. TBD

— Reply to this email directly, view it on GitHub https://github.com/canonical/rockcraft/issues/54#issuecomment-1220637061, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIX7ZIMKMHDOHR4SM6KREDVZ57BNANCNFSM564YBZBQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[SamirPS]

Rst to python ?

[cjdcordeiro]

I'm looking into this.

At first glance, although literate programming would be ideal, unlike Markdown, Sphinx doesn't have a lot of support for it. There is sphinx-litprog but it exports all the code-blocks into a single file, which is not what we want as we wouldn't be able to export different languages (YAML vs Bash) nor tell when one test starts and other finishes.

So I suggest:

Implementation plan

1. create a code folder under docs
2. for each documentation page (eg. "tutorials.rst") have a corresponding folder under docs/code (eg. docs/code/tutorials)
3. under each one of those folders, each test shall have its own folder as well (i.e. docs/code/tutorials/create_a_hello_world_rock)
4. each of these test folders can have any files that are relevant for the documentation's technical content (like a rockcraft.yaml file or bash scripts)
   • bash scripts will later be executed, as a whole, in a single test, so their filenames must be ordered such that we can guarantee a proper rendering of the test (eg. step1.sh, step2.sh, step2.2.sh, step3.sh...)
5. use Sphinx's include directive to include these files as code-blocks, ie.

   .. include:: code/tutorials/step1.sh
       :code: bash

6. add the tests/spread/docs suite to spread.yaml
7. then, from the automated spread tests, when initializing the GitHub actions workflow, dynamically add new spread tests into tests/spread/docs, by copying all the files from each docs' code folder and creating a task.yaml file that bundles together all the bash scripts into the execute section of that spread test

[sergiusens]

This looks good to me assuming that the testing driver is in task.yaml and we essentially pick up the content from docs/code.

For organizational purposes I might suggest creating a "tutorials" directory at the root of the documentation (and move the tutorials to there); and put "code" in there. We might in the future have a more convoluted way of testing "howtos" and having the separation from the start might be good