Future Documentation workflow

[wtrocki]

Resolves #1225 #1226

Motivation

1. Provide number of modifications in the CLI so we have level of flexibility when generating content and do not need 2 phase generator.
2. Avoid having generated documentation in main branch (as main branch will have unreleased changes
3. Provide solution for generating documentation on release for downstream and upstream - meeting all requirements.

I have removed generate-modular docs and will have content generation.
I still have docs in the repository present

How to support downstream

I think we can have dedicated branch that can be updated on the release of the CLI that will have generated content that is very specific to downstream. Our upstream content then will not be used by downstream if needed.

Tasks

• refactor codebase to support different requirements
• Drop rhoas prefix from titles
• Support generation of the index/assembly file from make generateDocs
• Integrate with content team requirements (regenerate proper content)
• [ ]

[pmuir]

Looks great generally.

[wtrocki]

My overal suggestion would be to see if we can:

• Format content to be downstream specific and do not present it in github main branch
• Push content to separate branch rather than keep it on main (automatically updated)
• Remove need for developers to push content itself to the main repo - we might need separate job to push it to our website as markdown files - this means that users can view released documentation and not what is currently in the development. This will mean less conflicts on documentation etc.

How this would work

I think we can have documentation for the CLI or think about webpage for RHOAS services.
if we keep documentation for CLI we can have job that triggers gh-pages update with markdown containing upstream docs. The same job can generate downstream specific docs on the downstream-docs branch.

FYI @rkpattnaik780 @craicoverflow

[bhardesty]

@wtrocki Thanks, I think this should work for the downstream. Would it be possible to tweak the file names and directories? Right now, it looks like all of the downstream command files and the readme are located in docs/commands/. Do you plan to have that on the main branch? I think it would work better with our downstream tooling if we put it on a separate branch, like we do now for modular-docs (that might be what you meant when you said something about a dedicated branch for downstream-specific content).

Could we also use the same directory structure and naming conventions that we currently use in modular-docs? That would mean:

• docs/commands/README.adoc -> assemblies/assembly-cli-command-reference.adoc
• docs/commands/.adoc -> modules/ref-.adoc (note the "ref-" prefix on each of these)
• In README.adoc, the include paths should all be include::../modules/ref-<command-name>.adoc[leveloffset=+1]

[wtrocki]

What I have done in this PR is to enable us to use released version of rhoas cli to generate docs (with some of the work done before by @craicoverflow)

So to answer your questions: all is possible by using cli command. I see next step to remove adoc documentation completely from main branch and replace it by markdown one.

How donwstream job works? Does it clone our repository? Does it call some make targets etc?

[wtrocki]

File format and structure is now corrected. Downstream build is setup.
I will now remove adoc files and replace them with markdown

[wtrocki]

@bhardesty Please view https://github.com/redhat-developer/app-services-cli/tree/downstream-docs

that is the new branch that contains freshly generated content based on this PR.

[wtrocki]

This will be enabled once approved. We use other trigger for testing

[wtrocki]

Markdown by default - same rules as with adoc (already replaced in the PR).
Downstream gets adoc files that are pushed to separate branch that no one will see.

[craicoverflow]

tip: md is already the default value, so you could omit it, if you wanted to.

[wtrocki]

Actually I will remove markdown files and generate them in separate PR

[wtrocki]

This will obviously fail the build so I will generate docs as last step before merge :D

[wtrocki]

Also let me know if we need more categories for subcomands etc. - That will be trivial to add on the same levels.

Nested levels in the index are separeate feature request :P

[wtrocki]

Found small bug in links on github, but that part will go away anyway.

[craicoverflow]

tip: md is already the default value, so you could omit it, if you wanted to.

[craicoverflow]

Why is this removing ./docs/commands, but then generating the documentation into a completely different directory?

[wtrocki]

Very good question. I think I need to provide documentation for that in the contributing to make it clear.

So the new workflow will split upstream and downstream:

1. We will have markdown ./docs/commands/ (./docs/commands/rhoas-cluster.md).
   I did not push that markdown here due to number of files created that will obfuscate already large PR
   Phase 2 for this would be to use that markdown with docusaurus website and create couple other placeholders like CLI guidelines etc.

2. We will have adoc/downstream pushed to different branch (only on releases) - for that we use ./dist/ folder that is gitignored so we can use it to push entire content to the new branch using github action.

[wtrocki]

Done end to end:

• Upstream website: https://redhat-developer.github.io/app-services-cli/
• Downstream branch: https://github.com/redhat-developer/app-services-cli/tree/downstream-docs

[bhardesty]

@wtrocki This looks awesome! I just have one small modification: for each included file, can you change the leveloffset from 1 to 2? For example: include::../modules/ref-completion.adoc[leveloffset=+2].

[wtrocki]