parent-context doesn't not work properly in deeper structures

[scholzj]

We tried to follow this documentation and use the templates for documentation in our project Strimzi. However, we have run into problems with the assembly template. The template suggests that on the beginning of every assembly, we should save the parent context:

:parent-context: {context}

And restore it at the end of every assembly.:

:context: {parent-context}

However, the template suggests that every assembly should use the same variable parent-context. And this works only on a very flat structure. Once you change the context on two levels you can very easily mess up the context for all the upper levels because the original context will be never restores.

As an example, you can check these two samples:

• Using an old template: https://github.com/strimzi/strimzi-kafka-operator/tree/modular-docs-parent-context/documentation/test
• Using the latest template: https://github.com/strimzi/strimzi-kafka-operator/tree/modular-docs-parent-context/documentation/test2

Just check these out and open them in your editor / render them and you will see how the context is never restored properly.

So far the solution we used in our docs was:

1. Remove every parent-context
2. When the context is actually changed, save and restore the context, but always use the different variable to not override the other parent contexts

Can you please clarify if we are using it incorrectly or if it is a bug?

[VladimirSlavik]

This would be a question primarily for @mrksu , but as his accomplice in doing this, I am sure this is indeed broken and your analysis is correct. In fact it confirms a doubt I had a few weeks earlier. (Curious that nobody ran into this, including me...)

The actual reason for doing this "parent-context" dance is that the "context" variable is global, too, and including a sub-assembly within an assembly messes context up: If the sub-assembly is followed by a module, the module gets wrong context.

An alternative approach is that in every file where there is an include::assembly followed by include::module, one must insert in between them a line setting context to the right value. It is not as neat and automatic, but works.

Sorry for brevity-hopefully it is understandable.

Asciidoc being what it is, it lacks variable scopes or stack-like structures, which leads me to believe an automated solution is not possible. We (Marek and I) agreed on proposing this solution, believing the stacking would happen automatically. Apparently it does not.

(PS: Do we need context to agree with the assembly? It is the sole reason to have this whole context and parent-context complication.)

[scholzj]

Setting the context again after each assembly include seems quite strange. But as I said - my workaround was removing all parent-context's and using different variables where the context actually changes.

Of course having local variables in Asciidoc would be great, but I assume that is not a realistic option.

BTW: This is an actual problem we run into in our docs. The two examples are just for demonstration. Maybe nobody else run into this yet because of using more flat document structures.

[ncbaratta]

An alternative approach is that in every file where there is an include::assembly followed by include::module, one must insert in between them a line setting context to the right value. It is not as neat and automatic, but works.

This was how I was doing it on the project @scholzj mentioned originally but I thought it seemed strange to repeat it over and over so I stopped doing that.

[msuchane]

Hi, sorry for replying so late.

As the person who invented the parent-context usage, I'm aware of this problem, and I think a semi-automated solution is possible.

The problem is that the parent-context attribute gets overwritten when another assembly (also using the same attribute) is included in it. As suggested, the attribute must have a unique name in each assembly to prevent it from being overwritten.

The newdoc script[1], which I've written for generating assembly and modules files from templates based on a title, solves the problem by naming the attribute parent-context-of-${assembly-ID}, where ${assembly-ID} is substituted with the actual ID of the assembly.

For example, if there's an assembly called "Creating a backup", its ID would be creating-a-backup and its parent context would be stored in the parent-context-of-creating-a-backup attribute. This would be really tedious if written by hand, which is why newdoc generates all this code for you.

I'm actively using this solution and I haven't found any problems with it.

I'm planning on merging the templates used internally by newdoc with the upstream templates in this project. When I get to it, I'd be happy to include this fix.

[1] https://github.com/redhat-documentation/tools/tree/master/newdoc

[scholzj]

@mrksu Thanks. I will try the newDoc utility. I guess we can close this issue, or?

[msuchane]

@scholzj Personally, I'd say it's useful to keep this issue open until I actually "merge" the two projects (enabling newdoc to use the templates from this repo directly), but closing it is fine by me, too.

[scholzj]

No, its fine to keep it open. Thanks.

[adahms]

@mrksu - Conducting a review of outstanding issues in this repo, and checking in to see if this issue can now be closed.

[stoobie]

I'll open by saying that whatever the solution, please update the Mod Docs reference guide.

Now...I'm running into a problem with parent-context...not sure if it's the same one noted here. But I noticed that the solution in the Mod Docs reference guide defines parent-context, but never undefines it. So I restructured the code a bit like this:

ifdef::context[:parent-context: {context}]
:context: customizing_engine_vm_deploy

My content.

ifndef::parent-context[:!context:]
ifdef::parent-context[]
:context: {parent-context}
:!parent-context:
endif::[]

Notice that I put the ifndef first.

[thatdocslady]

FYI, we ran into a similar problem in RHOSP and it turned out that we needed to set the :context: variable in the book/guide main assembly. This wasn't documented in the Mod Docs Reference Guide, and there is no template for master.adoc files so we had to scramble our own template for the team.

I'll be happy to add this information to the reference guide and work with someone who's more experienced with templates to create a book-level template, if this is indeed the best practice we want to implement across the teams.