git subtree-ing leads to warnings and inclusion of demo_docs and README.rst

[binwiederhier]

The readme page says the theme can be git subtree'd. As far as I can tell, this cannot be done without compilation warnings and the unexpected inclusion of some of the rst-files in the project root (README.rst) and demo_docs folder.

Example:

$ git remote add readthedocs git@github.com:snide/sphinx_rtd_theme.git
$ git fetch readthedocs
$ git subtree add --prefix=source/_themes readthedocs/master
$ make html

This creates a valid documentation, but it also includes the demo_docs resources and files for some reason (full output below):

/tmp/a/syncany-docs/source/_themes/README.rst:27: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:89: ERROR: Undefined substitution referenced: "problematic".
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:570: ERROR: Undefined substitution referenced: "*** Expect 6 errors (including this one). ***".
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:346: ERROR: Unknown target name: "5".
...

An easy fix for this is to manually delete all files and folders, except for the theme directory:

rm -rf bower.json demo_docs/ Gemfile* Gruntfile.js LICENSE MANIFEST.in package.json README.rst requirements.txt sass/ screen_* setup.py

But that obviously affects the git subtree, and I'm not entirely sure how updates/pulls from the subtree would be affected. Any idea how to solve this in a platform agnostic way (no symlinking)? A live example of this can be seen in the Syncany documentation (just started documenting, not much there yet).

Full compilation output:

$ make html
sphinx-build -b html -d build/doctrees   source build/html
Making output directory...
Running Sphinx v1.2.2
loading pickled environment... not yet created
building [html]: targets for 22 source files that are out of date
updating environment: 22 added, 0 changed, 0 removed
reading sources... [100%] what_is
/tmp/a/syncany-docs/source/_themes/README.rst:27: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:89: ERROR: Undefined substitution referenced: "problematic".
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:570: ERROR: Undefined substitution referenced: "*** Expect 6 errors (including this one). ***".
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:346: ERROR: Unknown target name: "5".
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:380: ERROR: Unknown target name: "hyperlink reference without a target".
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:393: ERROR: Duplicate target name, cannot be used as a unique reference: "duplicate target names".
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:89: WARNING: image file not readable: _themes/demo_docs/source/images/biohazard.png
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:None: WARNING: image file not readable: _themes/demo_docs/source/images/title.png
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:None: WARNING: image file not readable: _themes/demo_docs/source/images/title.png
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:None: WARNING: image file not readable: _themes/demo_docs/source/images/title.png
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:529: WARNING: image file not readable: _themes/demo_docs/source/images/biohazard.png
/tmp/a/syncany-docs/source/_themes/demo_docs/source/demo.rst:531: WARNING: image file not readable: _themes/demo_docs/source/images/biohazard.png
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:56: ERROR: Unknown directive type "automodule".

.. automodule:: test_py_module.test
    :members:
    :private-members:
    :special-members:
/tmp/a/syncany-docs/source/_themes/demo_docs/source/list.rst:24: ERROR: Unexpected indentation.
/tmp/a/syncany-docs/source/configuration.rst:11: ERROR: Unknown directive type "toc-tree".

.. toc-tree::
looking for now-outdated files... none found
pickling environment... done
checking consistency... /tmp/a/syncany-docs/source/_themes/README.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_connect.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_down.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_genlink.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_init.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_plugin.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_sy.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_syd.rst:: WARNING: document isn't included in any toctree
/tmp/a/syncany-docs/source/commands_up.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:: WARNING: using "math" markup without a Sphinx math extension active, please use one of the math extensions described at http://sphinx-doc.org/ext/math.html
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:30: WARNING: using "math" markup without a Sphinx math extension active, please use one of the math extensions described at http://sphinx-doc.org/ext/math.html
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:: WARNING: using "math" markup without a Sphinx math extension active, please use one of the math extensions described at http://sphinx-doc.org/ext/math.html
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:: WARNING: using "math" markup without a Sphinx math extension active, please use one of the math extensions described at http://sphinx-doc.org/ext/math.html
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:: WARNING: using "math" markup without a Sphinx math extension active, please use one of the math extensions described at http://sphinx-doc.org/ext/math.html
/tmp/a/syncany-docs/source/_themes/demo_docs/source/index.rst:: WARNING: using "math" markup without a Sphinx math extension active, please use one of the math extensions described at http://sphinx-doc.org/ext/math.html
writing output... [100%] what_is
None:355: WARNING: citation not found: nonexistent
writing additional files... genindex search
copying images... [100%] _static/installation_windows.png
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 32 warnings.

Build finished. The HTML pages are in build/html.

[dideler]

This issue affects us as well. We recently forked the theme at Freeseer/sphinx_rtd_theme so we can make minor modifications and subtreed it at Freeseer/freeseer.

But I just tried to build the docs and came across all the warnings as well. My first thought was to delete the demo files (I see @binwiederhier went a step further and deleted everything except the theme).

I also don't know how this would affect the subtree when getting updates. But since there's an extra step between our docs and upstream (our docs subtree -> our forked theme -> upstream theme) we should still be able to get updates from upstream by cherry picking them to our fork and then pulling in those changes via the subtree. Unfortunately, I think the process will be a bit more difficult in @binwiederhier's case.

[binwiederhier]

+1 for the comment; it's not a deal breaker, since the theme doesn't change very often (and doesn't have to), but it's a bit ugly that way...

[Blendify]

I talked to @ericholscher and this is not something that we really want to officially support.

[billsacks]

For anyone else this affects: I was able to fix these issues by including the following in my conf.py:

exclude_patterns = ["_themes/**"]