Repository: MongoEngine/mongoengine

Issue:
Docs: use vanilla sphinx RTD theme rather than duplicating it in the repo
Currently, [sphinx RTD theme](https://github.com/snide/sphinx_rtd_theme) is copied in the docs directory. Rather than duplicating, it would make sense to include it as a submodule, using latest release ([0.1.9](https://github.com/snide/sphinx_rtd_theme/releases/tag/0.1.9)).

And of course, in the future, try to follow new releases.



Discussion:
On second thought, rather than using a submodule, I think we should remove Sphinx RTD theme totally from the repo and install its [pip](%28https://pypi.python.org/pypi/sphinx_rtd_theme%29) (or package manager) version when building the docs.

In any case, the trick is that @rozza modified it to add a canonical URL feature. I sent [this PR](https://github.com/snide/sphinx_rtd_theme/pull/285) to Sphinx RTD theme so that they integrate this change upstream. Hopefully, it will be accepted and we'll be able to externalize the theme from the repo.

The PR was accepted. Once a new sphinx_rtd_theme is released, the whole theme can be externalized from MongoEngine without the functionality loss.
@lafrech if I understand correctly, these are the steps left before we can close this issue:

- [x] Wait for a new PyPI release of https://github.com/snide/sphinx_rtd_theme.
- [x] ~~Add `sphinx_rtd_theme==LATEST_VER`  to `requirements.txt`.~~
- [x] Replace `html_theme_path = ['_themes']` with `html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]` in `https://github.com/MongoEngine/mongoengine/blob/f9ccf635ca17e7f30efaeccba37b32c7ea062157/docs/conf.py#L103

And that should be it. Did I miss anything? Thanks for keeping an eye on this one!
There is a bit more to do in docs.conf to let it work both locally and on RTD.

I sent a PR with what I had done back then, rebased to latest master: https://github.com/MongoEngine/mongoengine/pull/1504.

Now, waiting for new sphinx RTD theme.
@yograterol, I don't wan't to be assigned this task, and I don't see the benefit of this "in progress" auto-tagging. Would you mind disabling whatever bot/service does this?
I've been pinging @yograterol about it here and over email several times with no response. @lafrech can we remove him from the organization?
I don't have the privileges either. @rozza? @thedrow?
Sorry, I do have required privileges. I removed @yograterol from the team. @yograterol please ask for reintroduction if this was wrong.

@wojcikstefan, you're now admin of team mongoengine.
@wojcikstefan, a new sphinx_rtd_theme version was released: 0.2.3.

About the requirements.txt part, the only place I see sphinx itself mentioned as a dependency is in the CONTRIBUTING.rst file, so I changed it to:

> If you want to test your documentation changes locally, you need to install
the ``sphinx`` and ``sphinx_rtd_theme`` packages.

Maybe we could mention the minimum version, here...

Anyway, the point here is not really which version is used by anyone building locally, but

- which version is used by RTD itself (do they use their latest minor version systematically?),
- and perhaps which version is used by packagers (for instance if Debian packager builds the docs automatically, I suppose they'll use the sphinx_rtd_theme version they package) if we care about distribution docs.

We could help by adding something like this to setup.py but I don't know if that would be useful to anyone:

    extras_require['docs'] = ['sphinx', 'sphinx_rtd_theme>='0.2.3]

I really don't know. I hope you're more familiar with this than I am.

In any case, as rozza said, it is not such a big deal if this canonical_url stuff is lost in the process.
Hmmm, in fact, building the docs with a sphinx_rtd_theme version older than 0.2.3 yields an error:

    Theme error:
    unsupported theme option 'canonical_url' given

I don't know if latest sphinx RTD theme is already available for use on RTD servers.

Resolving patch:
diff --git a/docs/_themes/sphinx_rtd_theme/__init__.py b/docs/_themes/sphinx_rtd_theme/__init__.py
deleted file mode 100755
--- a/docs/_themes/sphinx_rtd_theme/__init__.py
+++ /dev/null
@@ -1,17 +0,0 @@
-"""Sphinx ReadTheDocs theme.
-
-From https://github.com/ryan-roemer/sphinx-bootstrap-theme.
-
-"""
-import os
-
-VERSION = (0, 1, 5)
-
-__version__ = ".".join(str(v) for v in VERSION)
-__version_full__ = __version__
-
-
-def get_html_theme_path():
-    """Return list of HTML theme paths."""
-    cur_dir = os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
-    return cur_dir
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,6 +13,10 @@
 
 import sys, os
 
+import sphinx_rtd_theme
+
+import mongoengine
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -44,7 +48,6 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-import mongoengine
 # The short X.Y version.
 version = mongoengine.get_version()
 # The full version, including alpha/beta/rc tags.
@@ -97,10 +100,12 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'canonical_url': 'http://docs.mongoengine.org/en/latest/'
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_themes']
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -199,7 +204,3 @@
 #latex_use_modindex = True
 
 autoclass_content = 'both'
-
-html_theme_options = dict(
-    canonical_url='http://docs.mongoengine.org/en/latest/'
-)


Test patch: