Fix #571: Footer broken fix

[umcsdon]

Fix #571

Introduction:

This problem has been asked so many times in readthedoc's issue section, still no easy fix.

• readthedocs uses its own layout.html, so custom layout.html will be ignored (https://github.com/rtfd/readthedocs.org/issues/545)
• some other attempts on fix this problem(https://github.com/rtfd/readthedocs.org/issues/152)

What's worse, the footer is no longer inside

in sphinx_rtd_theme. It's inside some other div, so even hard to make changes.

My Procedure:

1. Grab the source code from sphinx_rtd_theme
2. Navigate to sphinx_rtd_theme folder

3. Modify the last section from footer.html:

   {% trans %}<a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}

   • to the following:

   {% trans %}<div class="footer">
   © 2013 FOSSLC
   | <a href="/contact.html">Contact us</a>
   | <a href="/sitemap.html">Sitemap</a>
   | <a href="https://github.com/Freeseer/freeseer/issues/new" target="_blank">Report an issue</a>
   </div>{% endtrans %}

4. Now, Copy the whole sphinx_rtd_theme folder(sphinx_rtd_theme source one) to our docs:

   cp ./sphinx_rtd_theme/* ../freeseer/docs/source/_themes/sphinx_rtd_theme/*

5. Then, modify the conf,py in our project to use the custom theme under _themes directory

   • Symlink or subtree the sphinx_rtd_theme/sphinx_rtd_theme repository into your documentation at docs/_themes/sphinx_rtd_theme then add the following two settings to your Sphinx conf.py file:

   html_theme = "sphinx_rtd_theme"
   html_theme_path = ["_themes", ]

   Result:

After completing above steps, I tested it under my readthedocs test account.

It works!!! http://freeseer-test-umcsdon.readthedocs.org/en/latest/

Note: sphinx_rtd_theme uses MIT license, so we can modify the source code for own use

[umcsdon]

Here is my fix. It requires pull the source code from sphinx_rtd_theme repo, and customize it.

It works.

@zxiiro @dideler

[dideler]

Nice work!

Now how do we proceed. Fork the Sphinx theme and subtree / submodule it? Or paste the files directly into our repo assuming we're happy with the theme and don't want updates? /cc @Freeseer/owners

Edit: I'm leaning towards subtree.

[umcsdon]

@dideler I think it also solves the logo problem. Just need to modify the {% block sidebartitle %} section inside layout.html(source) accordingly.

{% block sidebartitle %}
          <a href="{{ pathto(master_doc) }}" class="fa fa-home"> {{ project }}</a>
{% endblock %}

Edit: I will try it tonight.

[zxiiro]

+1 for subtreeing it

[umcsdon]

@dideler @zxiiro Should I close this one & subtreeing it in the next commit?

[dideler]

@umcsdon I forked the theme to Freeseer/sphinx_rtd_theme and added it as a subtree in the 621-rtd-theme-subtree branch. Does that work for you as a starting point? If so, I'll merge it in.

FYI, here is how I added the subtree, from the toplevel of working tree:

git remote add sphinx-rtd-theme git@github.com:Freeseer/sphinx_rtd_theme.git
git subtree add --prefix=docs/source/_themes/ sphinx-rtd-theme master --squash

[umcsdon]

@dideler That's awesome. Please merge it in.

[dideler]

@umcsdon I made a PR at #624 and want to give others a moment to leave their comments before merging it in. If no one opposes, I'll merge it in later today.

[umcsdon]

@dideler No problem.

[dideler]

@umcsdon you're good to go. You can use this existing PR if you want.