Workaround to include relative readme into docs directory #6
Conversation
The workaround is described in readthedocs/recommonmark#191 It is not perfect, but it does the job
docs/conf.py
Outdated
| app.add_config_value('m2r_anonymous_references', False, 'env') | ||
| app.add_config_value('m2r_disable_inline_math', False, 'env') | ||
| app.add_directive('mdinclude', MdInclude) | ||
|
|
There was a problem hiding this comment.
Do these changes also need to be added to the template itself? Meaning AUTO_STRUCTIFY_CONF in extension.py?
There was a problem hiding this comment.
We can add them to the template... it is a workaround and have some drawbacks... but they do allow usind mdinclude... which means that even files such as AUTHORS.md and CHANGELOG.md could be viable
There was a problem hiding this comment.
There is a recent PR that if accepted would lift the need for a workaround...
The approach used by recommonmark's own documentation is to include a symbolic link file inside the `docs` directory, instead of trying to do a `include`. References: readthedocs/recommonmark#191 sphinx-doc/sphinx#701 sphinx-doc/sphinx#7739
Obs.: Unfortunately it is not possible to convert docs/license.rst into markdown because the toctree directive needs a title and the original file is a TXT without one. So both steps are needed: (a) define a title and (b) use a special sphinx/reST directive (not available in recommonmark) to directly include the contents of another file.
|
Hi @FlorianWilhelm I changed the implementation of the workaround... References:
I will try to also do this with the templates and generated project in another PR. |
|
Okay, this even looks much cleaner. The only thing I find a bit dangerous is the symlinks. Do they even work on Windows? In sphinx-doc/sphinx#701 they say it might be problematic. Once this is merged I need to check if the dsproject extension still works since it directly depends on this. |
|
They "work" on Windows, if the user have setup the environment correctly. I was thinking about catching the exception and then re-raising something like this: class SymlinkError(OSError):
"""\
Impossible to create a symbolic link {{{link_path} => {original_file}}}.
If you are using a non-POSIX operating system, please make sure that
your user have the correct rights and that your system is corrctly
configured.
Please check the following references:
http://github.com/git-for-windows/git/wiki/Symbolic-Links
https://blogs.windows.com/windowsdeveloper/2016/12/02/ symlinks-windows-10/
https://docs.microsoft.com/en-us/windows/win32/fileio/ creating-symbolic-links
"""
def __init__(self, link_path, original_file, *args, **kwargs):
msg = (self.__class__.__doc__ or "").format(original_file, link_path)
super().__init__(msg, *args, **kwargs) |
|
I think this would help Windows users a lot. A lot of Windows users struggle to set Git up, let alone something more complicated. We already had several issues on Windows where PyScaffold couldn't even find Git although it was supposed to be installed. Windows is just a pain... |
|
I suppose we could go for it. If the Windows users still have problems even trying the documentation from git-for-windows and Microsoft, they still have 2 options: WSL and sticking with plain old rst... It is not like not using markdown would compromise a python project in terms of functionality... |
This follows the discussion in #6
This follows the discussion in #6
The workaround is described in readthedocs/recommonmark#191
It is not perfect, but it does the job, and now readthedocs have something to show...