[PATCH] doc improvements

[Chris Johns]

 [ Sorry, I did not see this post before ]

On 3/12/20 5:17 am, Sebastian Huber wrote:
> On 02/12/2020 18:09, Gedare Bloom wrote:
> 
>> A significant challenge with the version numbers arises during the release
>> process. I will leave all these doc patches for Chris to review/feedback, but
>> the concern is that when a release is cut all the version numbers need to be
>> injected to the release and then updated for the main branch.
> 
> I think its worth to have a closer look at the stuff provided by
> rtems-central/rtemsspec. The specification item based variable substitution is
> quite capable. You can execute arbitrary Python code to map a variable to a
> value. The RTEMS version numbers are already available in the build
> specification, so for example this patch

Interesting.

> diff --git a/spec/rtems/part/if/get-buffer.yml b/spec/rtems/part/if/get-buffer.yml
> index b2b13bd6..400909f9 100644
> --- a/spec/rtems/part/if/get-buffer.yml
> +++ b/spec/rtems/part/if/get-buffer.yml
> @@ -29,6 +29,8 @@ links:
>    uid: group
>  name: rtems_partition_get_buffer
>  notes: |
> +  In RTEMS ${/build/cpukit/optvermaj:/actions[0]/set-value} some things changed.
> +
>    This directive will not cause the running task to be preempted.
> 
>    The buffer start alignment is determined by the memory area and buffer size
> 
> Results in rtems-docs:
> 
> diff --git a/c-user/partition/directives.rst b/c-user/partition/directives.rst
> index e28ef2e..c5e6752 100644
> --- a/c-user/partition/directives.rst
> +++ b/c-user/partition/directives.rst
> @@ -381,6 +381,8 @@ the ``buffer`` parameter.
> 
>  .. rubric:: NOTES:
> 
> +In RTEMS 6 some things changed.
> +
>  This directive will not cause the running task to be preempted.
> 
>  The buffer start alignment is determined by the memory area and buffer size
> 
> The mapping from ${/build/cpukit/optvermaj:/actions[0]/set-value} to '6' is a
> bit long, but this could be simplified if needed.

Yes.

> 
> For the user manual of the Qualification Data Package of the ongoing ESA
> activity I generate the build output of an example application like this:
> 
>         self.config_mapper.add_get_value(
>             f"{self.config_item.type}:/example-make", self._get_example_make)
> 
> [...]
> 
>     def _get_example_make(self, _ctx: ItemGetValueContext) -> Any:
>         dir_state, _ = self.dependency("example")
>         status = run_command(["make", "clean"], cwd=dir_state.directory)
>         assert status == 0
>         stdout = []  # type: List[str]
>         status = run_command(["make"], cwd=dir_state.directory, stdout=stdout)
>         assert status == 0
>         content = SphinxContent()
>         with content.directive("code-block", value="none"):
>             content.add(stdout)
>         return "\n".join(content.lines)
> 
> So, instead of manually doing a copy and paste of some commands to document
> files, the content is generated automatically in the environment and the version
> corresponding to the package.
> 
> Each item has an "enabled-by" attribute. You can use this to differentiate a
> generation for a release document and a development branch document.

This looks nice. I have no time to play with this.

Chris