Switch visibility of blocks based on only-directive

[maldag]

Details

This is a feature request for the following use case:

• The developer of a manual wants to address different audiences in a single documentation.
  • The comissioning department basically needs a short cheatsheet of what is to be done
  • The service department needs the information above plus additional ideas of what errors can happen or explanation of how things are thought to be done.

Implementation idea in RST

Usage of only-directive can filter what text is being processed by sphinx using tags in the commandline. Thus, multiple outputs of the same projects can be produced.

Similar to different versions represented by different branches in RTD, different scopes shall be available. So the visibility matrix for a single project will be:

• Language
• Version
• Scope

[stsewd]

Usage of only-directive can filter what text is being processed by sphinx using tags in the commandline. Thus, multiple outputs of the same projects can be produced.

Is the request to allow users to specify what sphinxs tags to expose during build?

[maldag]

During the build process, the needed scopes would be accessible to administrators of the project only.

The end user needs a way to switch between scopes. For this I'm thinking about two ways:

• Same procedure as languages or versions (different page, different content)
• Put all paragraphs and boxes in collapsable boxes and only show content relevant to end user based an (cookie?)

[stsewd]

Hmm, why versions don't work for this use case? or maybe even better, subprojects.

With versions, you can have distinct contents, but you need to keep updated both versions in the same repo, that may be hard to mantain.

With subprojects, you can have two repos, one with simplified information and another one with the full docs.

Another solution, is using tags, you can have both texts in the same rst page. You can insert tags based on env variables #4603.

That way you can create two projects from one repo.

If you want to have this in the same page, I think you can use the sphinx-tab extension, you can check an example here https://docs.readthedocs.io/en/stable/development/install.html#requirements

[maldag]

I was thinking about using things like the sphinx tags or sphinx tab. Thanks for pointing out the reference on using tabs.

Using different versions would be too confusing for end users since it's the same software / product version, but a different scope.

I haven't thought about using subprojects yet. Would that be a way to use the foo tag for project 1 and the bar tag in project 2?

[stsewd]

Would that be a way to use the foo tag for project 1 and the bar tag in project 2?

Yes

[humitos]

It seems that we already offered a solution to the user. Please, @maldag if there is something else missing here, let us know and re-open the issue.