Add edit on github link to documentation pages

Signed-off-by: Julius Härtl <[email protected]>

Author: juliusknorr

_ext/edit_on_github.py

@@ -0,0 +1,47 @@
+"""
+Sphinx extension to add ReadTheDocs-style "Edit on GitHub" links to the
+sidebar.
+Loosely based on https://github.com/astropy/astropy/pull/347
+"""
+
+import os
+import warnings
+from pprint import pprint
+
+
+__licence__ = 'BSD (3 clause)'
+
+
+def get_github_url(app, view, path):
+    return 'https://github.com/{project}/{view}/{branch}/{path}'.format(
+        project=app.config.edit_on_github_project,
+        view=view,
+        branch=app.config.edit_on_github_branch,
+        path=path)
+
+
+def html_page_context(app, pagename, templatename, context, doctree):
+    if templatename != 'page.html':
+        return
+
+    if not app.config.edit_on_github_project:
+        warnings.warn("edit_on_github_project not specified")
+        return
+
+    if not app.config.current_docs:
+        warnings.warn("current_docs not specified")
+        return
+
+    path = app.config.current_docs + '/' + os.path.relpath(doctree.get('source'), app.builder.srcdir)
+    show_url = get_github_url(app, 'blob', path)
+    edit_url = get_github_url(app, 'edit', path)
+
+    context['show_on_github_url'] = show_url
+    context['edit_on_github_url'] = edit_url
+
+
+def setup(app):
+    app.add_config_value('edit_on_github_project', '', True)
+    app.add_config_value('current_docs', '', True)
+    app.add_config_value('edit_on_github_branch', 'master', True)
+    app.connect('html-page-context', html_page_context)

_shared_assets/themes/nextcloud_com/layout.html

@@ -205,6 +205,11 @@ <h1><a href="{{ pathto(master_doc) }}">{{ project|e }}</a></h1>
     <div class="text-center">
       <p>All documentation licensed under the <a href="https://creativecommons.org/licenses/by/3.0/us/">Creative Commons Attribution 3.0 Unported license</a>.</p>
       <p><a href="https://github.com/nextcloud/documentation/graphs/contributors">See who contributed to our documentation/credits</a>.</p>
+        {%- if show_source and has_source and sourcename and edit_on_github_url %}
+          <p>Do you want to help us to improve this document?
+            <a href="{{ edit_on_github_url }}" rel="nofollow">{{ _('Edit this page on GitHub') }} <span class="glyphicon glyphicon-pencil"></span></a>
+          </p>
+        {%- endif %}
     </div>
 </div>
 </div>

admin_manual/conf.py

@@ -29,7 +29,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinxcontrib.phpdomain', 'sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx']
+extensions += ['sphinxcontrib.phpdomain', 'sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../_shared_assets/templates']
@@ -292,3 +292,5 @@
   'user_manual': ('https://docs.nextcloud.com/server/%s/user_manual/' % (version), '../user_manual/_build/html/com/objects.inv'),
   'developer_manual': ('https://docs.nextcloud.com/server/%s/developer_manual/' % (version), '../developer_manual/_build/html/com/objects.inv'),
 }
+
+current_docs = 'admin_manual'

conf.py

@@ -1,6 +1,11 @@
 # global configuration for every documentation added at the end
 
-import os
+import os, sys
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+sys.path.insert(0, os.path.abspath(dir_path + '/_ext'))
+
+extensions = ['edit_on_github']
 
 # General information about the project.
 copyright = u'2012-2017, The Nextcloud developers'
@@ -14,11 +19,13 @@
 # The full version, including alpha/beta/rc tags.
 release = '13'
 
-
 # substitutions go here
 rst_epilog =  '.. |version| replace:: %s' % version
 
 html_context = {
 	'doc_versions': ['11', '12', '13'],
 	'current_doc': os.path.basename(os.getcwd()),
 }
+
+edit_on_github_project = 'nextcloud/documentation'
+edit_on_github_branch = 'master'

developer_manual/conf.py

@@ -29,7 +29,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinxcontrib.phpdomain', 'sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx']
+extensions += ['sphinxcontrib.phpdomain', 'sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../_shared_assets/templates']
@@ -303,6 +303,8 @@
   'user_manual': ('https://docs.nextcloud.com/server/%s/user_manual/' % (version), '../user_manual/_build/html/com/objects.inv'),
 }
 
+current_docs = 'developer_manual'
+
 from sphinx.builders.html import StandaloneHTMLBuilder
 StandaloneHTMLBuilder.supported_image_types = [
     'image/svg+xml',

user_manual/conf.py

@@ -29,7 +29,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx']
+extensions += ['sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../_shared_assets/templates']
@@ -304,3 +304,4 @@
   'developer_manual': ('https://docs.nextcloud.com/server/%s/developer_manual/' % (version), '../developer_manual/_build/html/com/objects.inv'),
 }
 
+current_docs = 'user_manual'

user_manual_de/conf.py

@@ -29,7 +29,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'rst2pdf.pdfbuilder']
+extensions += ['sphinx.ext.todo', 'rst2pdf.pdfbuilder']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../_shared_assets/templates']
@@ -294,4 +294,6 @@
 #epub_tocdup = True
 
 # Include todos?
-todo_include_todos = True
+todo_include_todos = True
+
+current_docs = 'user_manual_de'