Closed nicolaibonde closed 3 years ago
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?
Hi both @neobonde @iamEAP π
Hmm, let me just fully understand the use case.
βββ 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.
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.
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.
@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
@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).
@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
@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.
@iamEAP @emmaindal can someone check the PR I put?
Feature Suggestion
mkdocs-monorepo-plugin
should understand and support thedocs_dir
config in includedmkdocs.yml
files.Possible Implementation
Context
By supporting
docs_dir
in referencedmkdocs.yml
files, we open up a couple of nice use-cases:mkdocs.yml
configuration which contains subsets of documentation from submodules within a monorepo (while the submodules themselves have their own, completemkdocs.yml
files).README.md
, which is more conveniently kept at the submodule's root directory, rather than in adocs
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.