From cb8a8b7bd512baa0079289da7fad7e6a04da362e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Sat, 3 Feb 2018 11:39:36 +0100 Subject: [PATCH] Add edit on github link to documentation pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- _ext/edit_on_github.py | 47 +++++++++++++++++++ .../themes/nextcloud_com/layout.html | 5 ++ admin_manual/conf.py | 4 +- conf.py | 11 ++++- developer_manual/conf.py | 4 +- user_manual/conf.py | 3 +- user_manual_de/conf.py | 6 ++- 7 files changed, 73 insertions(+), 7 deletions(-) create mode 100644 _ext/edit_on_github.py diff --git a/_ext/edit_on_github.py b/_ext/edit_on_github.py new file mode 100644 index 000000000..67fcf6f9d --- /dev/null +++ b/_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) diff --git a/_shared_assets/themes/nextcloud_com/layout.html b/_shared_assets/themes/nextcloud_com/layout.html index e57f01e50..c18df88b7 100644 --- a/_shared_assets/themes/nextcloud_com/layout.html +++ b/_shared_assets/themes/nextcloud_com/layout.html @@ -205,6 +205,11 @@

All documentation licensed under the Creative Commons Attribution 3.0 Unported license.

See who contributed to our documentation/credits.

+ {%- if show_source and has_source and sourcename and edit_on_github_url %} +

Do you want to help us to improve this document? + {{ _('Edit this page on GitHub') }} +

+ {%- endif %}
diff --git a/admin_manual/conf.py b/admin_manual/conf.py index 6087a4378..facac13c2 100644 --- a/admin_manual/conf.py +++ b/admin_manual/conf.py @@ -29,7 +29,7 @@ from conf import * # 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 @@ intersphinx_mapping = { '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' diff --git a/conf.py b/conf.py index 02401409f..10279462b 100644 --- a/conf.py +++ b/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,7 +19,6 @@ version = '13' # The full version, including alpha/beta/rc tags. release = '13' - # substitutions go here rst_epilog = '.. |version| replace:: %s' % version @@ -22,3 +26,6 @@ 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' diff --git a/developer_manual/conf.py b/developer_manual/conf.py index e0fd41ab3..b2493de60 100644 --- a/developer_manual/conf.py +++ b/developer_manual/conf.py @@ -29,7 +29,7 @@ from conf import * # 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 @@ intersphinx_mapping = { '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', diff --git a/user_manual/conf.py b/user_manual/conf.py index a9d149080..936a5e106 100644 --- a/user_manual/conf.py +++ b/user_manual/conf.py @@ -29,7 +29,7 @@ from conf import * # 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 @@ intersphinx_mapping = { 'developer_manual': ('https://docs.nextcloud.com/server/%s/developer_manual/' % (version), '../developer_manual/_build/html/com/objects.inv'), } +current_docs = 'user_manual' diff --git a/user_manual_de/conf.py b/user_manual_de/conf.py index e87e8e7b4..800c37436 100644 --- a/user_manual_de/conf.py +++ b/user_manual_de/conf.py @@ -29,7 +29,7 @@ from conf import * # 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_copyright = u'2012-2017, Die Nextcloud Entwickler' #epub_tocdup = True # Include todos? -todo_include_todos = True \ No newline at end of file +todo_include_todos = True + +current_docs = 'user_manual_de'