mkdocs - Githubissues

szcf-weiya commented 3 years ago

revision date for mkdocs

try to add the revision date plugin https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin/tree/master for ESL-CN currently, no plugins, if I add the plugin via

# file mkdocs.yml
plugins: 
  - git-revision-date

it throws

$ mkdocs serve
INFO    -  Building documentation... 
/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/git/cmd.py:914: UserWarning: Python 3.5 support is deprecated and will be removed 2021-09-05.
It does not preserve the order for key-word arguments and enforce lexical sorting instead.
  "It does not preserve the order for key-word arguments and enforce lexical sorting instead.")
/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/git/cmd.py:914: UserWarning: Python 3.5 support is deprecated and will be removed 2021-09-05.
It does not preserve the order for key-word arguments and enforce lexical sorting instead.
  "It does not preserve the order for key-word arguments and enforce lexical sorting instead.")
WARNING -  Config value: 'enable_search'. Warning: Unrecognised configuration name: enable_search 
WARNING -  Config value: 'esl_url'. Warning: Unrecognised configuration name: esl_url 
WARNING -  Config value: 'extra_javascript'. Warning: Some files in your 'docs_dir' are not listed in the 'extra_javascript' config setting and will be ignored by the theme. Add the following files to the 'extra_javascript' config setting if you want them to have an effect on the theme: ['js/360.js', 'js/baiduzhanzhang.js', 'js/iDisqus-20190225.min.js', 'js/iDisqus.min.js', 'js/iDisqus0.min.js', 'js/iDisqus190507.min.js', 'js/mathjax.js'] 
INFO    -  Cleaning site directory 
ERROR   -  Error building page index.md 
Traceback (most recent call last):
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/bin/mkdocs", line 11, in <module>
    sys.exit(cli())
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/mkdocs/__main__.py", line 127, in serve_command
    livereload=livereload
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/mkdocs/commands/serve.py", line 117, in serve
    config = builder()
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/mkdocs/commands/serve.py", line 112, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/mkdocs/commands/build.py", line 282, in build
    build_pages(config, dirty=dirty)
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/mkdocs/commands/build.py", line 242, in build_pages
    _build_page(page, config, site_navigation, env)
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/mkdocs/commands/build.py", line 134, in _build_page
    'page_markdown', page.markdown, page=page, config=config, site_navigation=site_navigation
  File "/media/weiya/PSSD/Programs/anaconda3/envs/py35/lib/python3.5/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
TypeError: on_page_markdown() got an unexpected keyword argument 'site_navigation'

szcf-weiya commented 3 years ago

why I did not upgrade mkdocs from 0.17.2 to 1.0

the major reason is that the URL will be changed, and I need to migrate the Disqus comments https://www.mkdocs.org/about/release-notes/#version-10-2018-08-03

szcf-weiya commented 3 years ago

analyze the reason

the error should be caused due to the incompatibility between mkdocs0.17.2 and mkdocs1.0+ as introduced in https://www.mkdocs.org/user-guide/plugins/ the method has the following four parameters, which are exactly the four arguments written in the plugin, https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin/blob/71c6e115bad0ee00987792aca234128f6309e89c/mkdocs_git_revision_date_plugin/plugin.py#L29 but for mkdocs0.17, the documentation shows that the fourth argument name is different, and actually, that is the reported error message,

TypeError: on_page_markdown() got an unexpected keyword argument 'site_navigation'

Then there would be two choices:

upgrade mkdocs
modify the plugin

the second one would be better in terms of no changes on the URLs as said above.

szcf-weiya commented 3 years ago

modify the plugin git-revision-date

first of all, fork it

first attempt

change

def on_page_markdown(self, markdown, page, config, files):

to

def on_page_markdown(self, markdown, page, config, site_navigation):

then install the package via

$ python setup.py install

then run mkdocs serve, it throws

  File "/media/weiya/PSSD/Programs/anaconda3/envs/py367/lib/python3.6/site-packages/mkdocs_git_revision_date_plugin-0.3-py3.6.egg/mkdocs_git_revision_date_plugin/plugin.py", line 42, in on_page_markdown
AttributeError: 'Page' object has no attribute 'file'

In mkdocs1.x, Page is defined in https://github.com/mkdocs/mkdocs/blob/e1b77ab66e8305b5f0373b4842b50d2618390a96/mkdocs/structure/pages.py#L17 but in mkdocs0.17, https://github.com/mkdocs/mkdocs/blob/9ef0ff731d4aade0b68b84bfcbcfd2140067f70a/mkdocs/nav.py#L151-L157 no file attribute

second attempt

use abs_url to get the file location, change

revision_date = self.util.get_revision_date_for_file(page.file.abs_src_path)

to

revision_date = self.util.get_revision_date_for_file(page.abs_url.replace("/index.html", ".md"))

since I had set use_directory_urls: false, then the URLs always end with /index.html. It throws,

  File "/media/weiya/PSSD/Programs/anaconda3/envs/py367/lib/python3.6/site-packages/git/cmd.py", line 828, in execute
    raise GitCommandError(command, status, stderr_value, stdout_value)
git.exc.GitCommandError: Cmd('git') failed due to: exit code(128)
  cmdline: git log --date=short --format=%ad -n 1 /Preface/2016-07-20-Preface-to-the-Second-Edition.md
  stderr: 'fatal: ambiguous argument '/Preface/2016-07-20-Preface-to-the-Second-Edition.md': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]''

so I need to add the prefix docs.

Also note that the default /index.md is directly rendered as /index.md, then the replacing returns .md, no such file, then it will throws

cmdline: git log --date=short --format=%ad -n 1 docs.md
  stderr: 'fatal: ambiguous argument 'docs.md': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]''