Add support for docs_dir mkdocs.yml config

[nicolaibonde]

Feature Suggestion

mkdocs-monorepo-plugin should understand and support the docs_dir config in included mkdocs.yml files.

Possible Implementation

We have access to the config of the included mkdocs.yml in the parser, which means we can get the docs_dir.

Context

By supporting docs_dir in referenced mkdocs.yml files, we open up a couple of nice use-cases:

• The possibility to reference a sibling mkdocs.yml configuration which contains subsets of documentation from submodules within a monorepo (while the submodules themselves have their own, complete mkdocs.yml files).
• The possibility for simpler submodule topologies with simpler documentation needs (e.g. submodules which only need a single README.md, which is more conveniently kept at the submodule's root directory, rather than in a docs sub-folder)

Naturally, other use-cases would be possible as well.

Original Report

Hi i was wondering if it would be possible to allow for the use of docs_dir attribute in a mkdocs.yml config file

My issue is that we have a submodule that is used in many projects, and it has a lot of documentation. These many projects don't all need the full documentation from the submodule, but only a subset.
There for the idea was to create a mkdocs_submodule.yml in the root git repository that only includes the needed documentation.

This would allow us to build tailored documentation packages for each of our projects.

[iamEAP]

Hmm... I can't see a reason why we wouldn't want to support docs_dir in this plugin. @emmaindal, do you happen to have any history on this? Do you know if the current lack of support was an oversight, or an explicit decision?

[emmaindal]

Hi both @neobonde @iamEAP 👋

Hmm, let me just fully understand the use case.

1. You have the following structure

├── docs
│   └── index.md
├── mkdocs.yml
├── v1
│   ├── docs  <---- 3. so that the name of this directory can be something else?
│   │   └── reference.md
│   └── mkdocs.yml    <--- 2. you want it to be possible to add docs_dir to this mkdocs.yml?

I agree with that I don't see any reasons to why not support it, we do have access to the config of the subfolders mkdocs.yml in the parser which means we can get the docs_dir on subfolder level. I guess the need has not been there before which could be the reason to the decision. But let me loop in @bih in case you have more of a background story.

[nicolaibonde]

Hi @iamEAP and @emmaindal

Thanks for taking the time to help me out!

The use case is that we have a submodule that requires its own documentation, but in the main repo we also want documentation, some of it is from the submodule and some of it is unique to the main repo.
But not all the documentation in the submodule is required, therefore I wanted to create two mkdocs.yml files in the main repo, one for the subset of submodule documentation and one as the primary documentation that includes the submodule documentation.

├── docs
│   └── index.md
├── mkdocs.yml
├── submodule_mkdocs.yml   <--- Subset of documentation in submodule/docs, in this example only. submodule/docs/reference.md
├──  submodule
│   ├── docs 
│   │   └── index.md
│   │   └── reference.md
│   └── mkdocs.yml  <--- Full and normal documentation of submodule, independent of main repo.

Hope it is possible in someway to get this to work, i guess instead of a different docs_dir it could also be that you can include single .md files from other directories, but I assume that this is a major step away from what monorepo is made for.

[haneul]

I posted somewhat similar request with #41 Our use case is something like

├── docs
│   └── index.md
├── mkdocs.yml
├── src_mkdocs.yml   <--- Some docs to be with actual source
├──  src
│   ├── service1 
│   │   └── readme.md
│   ├── service2
│   │   └── readme.md

with this structure some of documents can be in the same directory with the source code. while docs can maintain more general docs.

[iamEAP]

@neobonde, would it be suitable as a workaround to place the submodule_mkdocs.yml within the submodule (but maybe named a little more intuitively), and then !include that file?

Something like:

├─ docs/
│  ├─ index.md
├─ submodule/
│  ├─ docs/
│  │  ├─ index.md
│  │  ├─ reference.md
│  ├─ mkdocs.yml             <--- Full submodule docs
│  ├─ mkdocs_in_context.yml  <--- Subset suitable for reference within a monorepo context
├─ mkdocs.yml                <--- Uses !include ./submodule/mkdocs_in_context.yml

I guess the maintenance becomes a little annoying (updating what gets included in the monorepo context is done in the submodule...)?

And @haneul, perhaps you've already considered this, but in a setup like the one you've outlined, there may be risk of exposing your source code in ways that you maybe don't intend in such a configuration, e.g.

├── docs
│   └── index.md
├── mkdocs.yml
├── src_mkdocs.yml
├──  src
│   ├── service1 
│   │   ├─  oops.js    <!--- Would be copied as a static asset into the built docs folder
│   │   └── readme.md
│   ├── service2
│   │   ├─  src        <!--- Anything under here too.
│   │   └── readme.md

[haneul]

@iamEAP That's fair point so we may need to have a way to include/exclude more flexibly for that as well. In our situation, exposing those is okay (while not ideal).

[nicolaibonde]

@iamEAP I mean it is possible of course, but it would put a dependency for one project into another, since the submodule is widely used by many of our clients. Also this could expose details about projects to other customers

[iamEAP]

@neobonde, ah yeah, that makes sense.

Yeah, this seems totally feasible and something we'd gladly include in the plugin. I've synthesized the thread so far into a feature request at the top, including Emma's implementation detail recommendations, and labeled it as such.

To be totally transparent: the team internally probably won't have the cycles to implement anytime soon. That being said! We dedicate time to reviewing/triaging/supporting, and we're here to help y'all (in this thread, or future travellers from the internet) however we can.

[haneul]

@iamEAP @emmaindal can someone check the PR I put?