[PATCH] doc improvements

[Sebastian Huber]

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

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.

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.

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hubere at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/