How to avoid redundancy between documentation files

[musslick]

@younesStrittmatter @hollandjg
To avoid redundancies between documentation files within the same package, I was wondering if it makes sense if we add the markdown-include extension into our contribution template?

See this page for an explanation.

https://stackoverflow.com/questions/35918976/mkdocs-eliminate-copy-paste-in-files

[hollandjg]

It's really tricky. I'd suggest avoiding duplication wherever possible, and otherwise just biting the bullet and using copy/paste and find/replace for those bits of code.

The markdown-include package has the same problems as the pymdownx.snippets extension @younesStrittmatter and I were trying to use for the workflow documentation, namely:

• It can't include files from relative paths, so you have to use absolute paths
• When we do the multi repo merge of the documentation, the absolute paths have to change

To really make use of this, we might need to either:

• make a change to mkdocs to allow for relative paths, and then upgrade the markdown-include (or the pymdownx snippets extension) to use that, or
• change the multi repo plugin so that it doesn't mess up our paths.

@younesStrittmatter had a look at the multi repo plugin – perhaps he can say more about the possibilities there.

[younesStrittmatter]

We can make it work:

pymdownx.snippets:
base_path: ["temp_dir/user-guide/experimentalists/pooler-1"]
markdown_include.include:
base_path: "temp_dir/user-guide/experimentalists/pooler-1"

in the base.yml of the autora-parent makes it work.

Problem:
We need to figure out to give diffferent base_paths to different imported repositories

[younesStrittmatter]

• This is for an test-repository I created. The base_path will be dependent on the name of the repository but will always be something like temp_dir/user-guide/ ....

[hollandjg]

Did we decide just to not do this? Can we close this discussion? @younesStrittmatter

[younesStrittmatter]

Yes. We don't do it. Can be closed

[younesStrittmatter]

Yes