Github automation assistance needed - Eclipse ThreadX documentation

Summary

I am working with the WebDev team to publish the official ThreadX documentation set to threadx.io

The documentation source is in AsciiDoc; you will find it here: https://github.com/eclipse-threadx/rtos-docs-asciidoc

I would like to have automation setup so that, when I will merge documentation PRs, a new HTML rendition is generated and committed to this repository: https://github.com/eclipse-threadx/rtos-docs-html

Then, this new HTML version would in turn be published to the ThreadX website automatically.

I worked with AsciiDoctor to convert from AsciiDoc to HTML.

The rtos-docs-html repository, for the time being, contains an HTML version I generated semi-manually. I essentially wrote a bunch of bash scripts to traverse the repository structure of the AsciiDoc source and invoke AsciiDoctor on each .adoc file. However, those scripts are not production quality. AsciiDoctor does not offer a batch mode.

I have no idea hot to automate all of this, since I never touched GitHub actions before. I am happy to write a robust bash script to perform the conversion itself if that could help.

See further details in the issue below: eclipsefdn/it/websites/threadx.io#10

I have been told either @eclipsefdn/it/releng or @netomi could potentially assist me.

I appreciate your support.

Priority

• Urgent
• High
• Medium
• Low

Severity

• Blocker
• Major
• Normal
• Low

Impact

We

mentioned in issue eclipsefdn/it/websites/threadx.io#10

so there is a nice tutorial on how to automatically build with asciidoctor and publish the generated site in a workflow:

https://medium.com/james-reads-public-cloud-technology-blog/auto-build-and-host-pretty-html-documentation-using-asciidoc-github-pages-github-actions-758a03f93d7d

looks pretty straight-forward. In your case you dont wanna push to GH Pages but instead commit to the other repo. We can help you setup ofc. I am in Brussels till tomorrow, so I can work on that Wednesday if nobody steps up before.

added team:releng label

assigned to @netomi

can you maybe share the scripts that you have been using so far to generate the html pages?

I want to verify that I do exactly the same.

@netomi I copied the relevant script below.

Essentially, you need to copy every media directory as is and invoke asciidoctor on every .adoc file.

I don't deal with folders with subfolders, but I resisted the temptation to make it recursive, as I expected I would not use it in the future. This is why the destination is hardcoded.

DESTINATION="/mnt/c/code/threadx/rtos-docs-html/"

for directory in `ls -d */`; do
   if [ "$directory" != "media/" ]; then
    echo "$directory"
    CURRENT_DESTINATION=${DESTINATION}/${directory}
    mkdir ${CURRENT_DESTINATION}
    (cd "$directory" && asciidoctor *.adoc --destination-dir=${CURRENT_DESTINATION})
    (cd "$directory" && cp -R media ${CURRENT_DESTINATION})
   fi
done

mentioned in issue #5401 (closed)

So I have created https://github.com/eclipse-threadx/rtos-docs-asciidoc/pull/4 And also added the necessary token to push the changes to the html repo.

Once merged it should work.

I wanted to say that it would have been easier if the source and html pages are in the same repo, but it should work now like that.

at release engineers: I have created a fine-grained token for pushing the generated content from the asciidoc repo to the html repo. It only has access to the html repo with write permissions to the contents. Its pushed to pass as well and included in the otterdog config.

added IT-prioritylow IT-severitylow labels

added service:GitHub label

added service:otterdog label

Closing as it is working now.

closed