Make documentation linking more explicit

[loganharbour]

Reason

Documentation linking can be an absolute nightmare if a user is not very explicit. For example, one can link to tutorials/index.md because they have some getting_started/tutorials/index.md page that they're too lazy to type out. But... guess what the odds are that tutorials/index.md can be found in another app, or in framework, or in modules? You guessed it, the odds are yuge.

With this, there is a significant desire to force users to be explicit about linking. Making a small change in framework documentation to suddenly collide with multiple applications is not worth our time.

Design

We already have the ability to mark included content with a unique key of sorts in the config files. Kind of. We have two ways to include content:

Content:
    - framework/doc/content
    - tensor_mechanics:
        root_dir: modules/tensor_mechanics/doc/content
        <other things...>

I propose that we get rid of the first method, and require the definition of content using the latter method. With this, we are then able to provide additional context as to where we want content to come from.

For example, let's say we want to link to a file in tensor mechanics from within a file in modules/doc/content. We would link to this as such:

See my awesome link: [tensor_mechanics:cool_markdown.md]

Any linking that is done without the additional context (without the tensor_mechanics: in the example above) will only search for content from within the root directory that that content is stored in. TLDR: If you want to link to something that something else provides, you MUST state where it comes from.

Steps to get this done:

1. Change all config.yml MooseDocs configs in moose and all apps to define their content using the method above. This can be done ahead of time.
2. Implement the thing above, but still allow for searching outside of your content.
3. Script up something that will automatically insert all of the explicit keys and run that on all apps.
4. Don't allow searching outside of your content.
5. Profit?! 💰

Impact

Significant change to how folks use MooseDocs. But, we should be able to mitigate this by providing useful error messages and searching for content in other keys, suggesting to the user what prefix to use.

[loganharbour]

@aeslaughter I know we get your attention every once in a while... I'll welcome any feedback I can get here :-)

[joshuahansel]

My only caution is that it requires that all apps use the same naming for the "outside" content. For example, if a Sockeye page links to a MOOSE page with the content key "moose" and Bison links to a MOOSE page with the content key "framework", then that would be a problem in DireWolf docs, since the MOOSE content key cannot both be "moose" and "framework". I think we'd rarely run into this situation, since we're pretty consistent across apps, but it's at least a possibility. In that case, we can just ask the dev to use the "standard" key, so I think it's not really a problem.

1. Probably need to clarify "the method above": I guess you just mean the "key" method, e.g.,

   Content:
    - tensor_mechanics:
        root_dir: modules/tensor_mechanics/doc/content

2. Good
3. Can we generate "deprecated" failures in MooseDocs? Maybe a script is less work and time though, since devs may not timely address deprecated failures.
4. Good
5. Correct

I think this is a great idea.

[loganharbour]

My only caution is that it requires that all apps use the same naming for the "outside" content. For example, if a Sockeye page links to a MOOSE page with the content key "moose" and Bison links to a MOOSE page with the content key "framework", then that would be a problem in DireWolf docs, since the MOOSE content key cannot both be "moose" and "framework". I think we'd rarely run into this situation, since we're pretty consistent across apps, but it's at least a possibility. In that case, we can just ask the dev to use the "standard" key, so I think it's not really a problem.

I talked with Casey about this one. I don’t think it will actually happen, but we do have a solution that involves defining content with alternate keys.

[loganharbour]

Can we generate "deprecated" failures in MooseDocs? Maybe a script is less work and time though, since devs may not timely address deprecated failures.

yeah. I played around with something like this last night. I think that adding the following command line options to extensions will help:

• explicit (default False, remove once apps fixed): Enable explicit checking. That is, if a key isn’t given, load from content from that same root_dir only
• migrate_explicit (default Flase): Same as above but make a warning that provides a diff on how to make things explicit if only one match is found on another key
• ignore_keys (default True for now): whether or not to ignore the keys set. This is so that we can make things explicit in moose, but ignore them in the apps until the apps setup keys in their config.

[milljm]

Would also like to take care of: #23905 while we're at it.

[loganharbour]

Would also like to take care of: #23905 while we're at it.

Yep. This will enable that. @cticenhour hoped for the same when I discussed this with him.

[permcody]

This is great! I support this! However, I do think that Josh's concern is genuine. We really should have a naming convention that's easier to verify. I would recommend using the App name (like we do for dynamic loading) or the repository name. By doing so, we eliminate Josh's concern completely, but we also enable the other feature I want, which is to make links automatically optional if submodules are optional and turned off for a particular build. To be clear, I want to be able to say [griffin:transport_solver.md] and have that not fail if we are building an application like BlueCRAB with the Griffin module turned off.

[GiudGiud]

I think this is good. And it will help us on the VTB if we ever want to pull in documentation from the apps.