search

backstage / mkdocs-monorepo-plugin

✚ Build multiple documentation folders in a single Mkdocs. Designed for large codebases.
https://backstage.github.io/mkdocs-monorepo-plugin/
Apache License 2.0
316 stars 74 forks source link

Incompatibility with timvink/mkdocs-git-revision-date-localized-plugin #12

Closed prcr closed 4 years ago

prcr commented 4 years ago

Hello,

I was trying to use the MkDocs plugin timvink/mkdocs-git-revision-date-localized-plugin in my project but it always fails with:

$ mkdocs build
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/prcr/Codacy/git/docs/site 
ERROR   -  Unable to read git logs of '/tmp/docs_kvh_ua8a/index.md'. To ignore this error, set option 'ignoring_missing_git: true'
ERROR   -  Error reading page 'index.md': Cmd('git') failed due to: exit code(128)
  cmdline: git log --date=short --format=%at -n 1 /tmp/docs_kvh_ua8a/index.md
  stderr: 'fatal: /tmp/docs_kvh_ua8a/index.md: '/tmp/docs_kvh_ua8a/index.md' is outside repository' 
[...]

I was able to pinpoint the issue to the fact that I'm using mkdocs-monorepo-plugin as well. It seems that the plugin copies the *.md files to a temporary directory before building them, and this way the other plugin cannot use git log to find out the last updated date of the Markdown files.

timvink commented 4 years ago

I see that mkdocs-monorepo-plugin copies the contents of multiple docs/ dirs into a temporary docs_/ directory at the MkDocs event on_config().

mkdocs-git-revision-date-localized-plugin uses the event on_page_markdown(), and then specifically the page.file.abs_src_path attribute of a page in order to run git log on the file location. If the file is copied to a temp folder the git info is lost, and the git log fails.

One possible solution might be to use symlinks to the temporary docs_/ folder instead of copying files. That way hopefully the abs_src_path remains intact. So replace:

https://github.com/spotify/mkdocs-monorepo-plugin/blob/3cf93fa0d433a35f3d850ffa13de2d00462e3f68/mkdocs_monorepo_plugin/merger.py#L59

with:

copytree(source_dir, dest_dir, symlinks=True)

I haven't tested this yet, but I am willing to give it a try and provide a PR?

Edit: Another possible solution could be to save during on_config() for each file the source location in a dictionary of the Plugin class. Then use on_pre_page() to "alter the Page instance", in effect replacing the abs_src_path attribute with the original source.

bih commented 4 years ago

@timvink That sounds like an interesting approach and definitely has pros compared to how we do it today of constructing a new docs/ directory in the /tmp temporary filesystem. Looking forward to seeing what your approach is and happy to provide feedback :)

timvink commented 4 years ago

Cool, will pick this up somewhere in next week!

timvink commented 4 years ago

The symlink approach didn't work, but I got it working with the second idea. Opened https://github.com/spotify/mkdocs-monorepo-plugin/pull/13, let's discuss details there!