Update for new sphinx version

Rename README.sphinx to enable markdown presentation
Add instructions for new pages and internationalisation
2021-07-21 15:26:34 +10:00 · 2018-08-28 19:59:33 +10:00 · 2018-08-28 19:57:27 +10:00 · 2018-03-26 20:09:52 +11:00 · 2016-12-24 22:28:11 +00:00 · 2016-12-13 16:34:19 +01:00
8 changed files with 268 additions and 45 deletions
--- a/README.md
+++ b/README.md
@ -8,27 +8,22 @@ To build the documentation see README.sphinx.

 Rendered versions are available online:

- User Guide - <https://karp.id.au/social/user/>
- Admin Guide - <https://karp.id.au/social/admin/>
+- User Guide - <http://thomask.sdf.org/social/en/user/>
+- Admin Guide - <http://thomask.sdf.org/social/en/admin/>

 ## License

- Copyright 2016 Thomas Karpiniec <tk@1.21jiggawatts.net>. (If this ever becomes official documentation then obviously copyright will be assigned to the FSF.)
+- Copyright 2018 Thomas Karpiniec <tk@1.21jiggawatts.net>.
 - Copyright 2015 Free Software Foundation, Inc.
 - Copyright 2015 StatusNet, Inc
+- Contributors retain copyright of their work. See git history for details. Thank you:

-This documentation is made available under the terms of the Creative Commons Attribution 3.0 Unported license. See <http://creativecommons.org/licenses/by/3.0/> for details.
-
-## Contributors
-
-A huge thank you to everybody who has contributed to these manuals:
-
+@drymer, for the Spanish translation  
 Scott Bragg @faulteh  
 John Kristensen @jerrykan

+This documentation is made available under the terms of the Creative Commons Attribution 3.0 Unported license. See <http://creativecommons.org/licenses/by/3.0/> for details.

 ## Acknowledgements

 Much of the initial content is copied and adapted from the documentation in the main GNU social project at <https://git.gnu.io/gnu/gnu-social/> under the terms of Creative Commons Attribution 3.0 Unported license.
-
-
--- a/README.sphinx
+++ b/README.sphinx
@ -1,22 +0,0 @@
-Install Sphinx
--------------
-Install Sphinx from Debian repositories:
-
-    apt-get install python-sphinx
-
-Install Sphinx using virtualenv (assumes virtualenv is already installed):
-
-    virtualenv venv
-    source venv/bin/activate
-    pip install -r requirements.txt
-
-
-Build Documentation
-------------------
-The documentation can be generated using the following commands
-
-    cd docs/
-    make html
-
-The documentation should now be available in `_build/` directory under the
-`docs/` directory.
--- a/README.sphinx.md
+++ b/README.sphinx.md
@ -0,0 +1,45 @@
+Install Sphinx
+--------------
+Install Sphinx from Debian repositories:
+
+    apt-get install python-sphinx
+
+Install Sphinx using virtualenv (assumes virtualenv is already installed):
+
+    virtualenv venv
+    source venv/bin/activate
+    pip install -r requirements.txt
+
+
+Build Documentation
+-------------------
+The documentation can be generated using the following commands
+
+    cd docs/
+    make html
+
+The documentation should now be available in `_build/` directory under the
+`docs/` directory.
+
+To generate the Spanish translations:
+
+    cd docs/
+    make translations
+
+The Spanish version will be generated in `docs/_build/spanish`.
+
+New Pages and Internationalisation
+----------------------------------
+Translation works using `sphinx-intl`. It creates .po files where English phrases can be converted to other languages.
+
+To add a page and create the .po file for translation:
+
+1. Set up the virtualenv as described above. Activate it and install the requirements.
+2. Create a new file for the page such as `admin/file.rst`.
+3. Edit it and make it correct in English (`make html`).
+4. Open terminal to `/docs` and run `make gettext`. This creates files under `_build/locale`
+5. Run `sphinx-intl update -p _build/locale/ -l es` to refresh the .po files
+6. Edit .po files under `locale/es/LC_MESSAGES/...`
+7. Run `make translations` to generate the Spanish version
+8. Commit changes.
+
--- a/docs/_templates/layout.html
+++ b/docs/_templates/layout.html
@ -0,0 +1,204 @@
+{# TEMPLATE VAR SETTINGS #}
+{%- set url_root = pathto('', 1) %}
+{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
+{%- if not embedded and docstitle %}
+  {%- set titlesuffix = " &mdash; "|safe + docstitle|e %}
+{%- else %}
+  {%- set titlesuffix = "" %}
+{%- endif %}
+
+<!DOCTYPE html>
+<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
+<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
+<head>
+  <meta charset="utf-8">
+  {{ metatags }}
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  {% block htmltitle %}
+  <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
+  {% endblock %}
+
+  {# FAVICON #}
+  {% if favicon %}
+    <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
+  {% endif %}
+
+  {# CSS #}
+
+  {# OPENSEARCH #}
+  {% if not embedded %}
+    {% if use_opensearch %}
+      <link rel="search" type="application/opensearchdescription+xml" title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}" href="{{ pathto('_static/opensearch.xml', 1) }}"/>
+    {% endif %}
+
+  {% endif %}
+
+  {# RTD hosts this file, so just load on non RTD builds #}
+  {% if not READTHEDOCS %}
+    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
+  {% endif %}
+
+  {% for cssfile in css_files %}
+    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {% endfor %}
+
+  {% for cssfile in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {% endfor %}
+
+  {%- block linktags %}
+    {%- if hasdoc('about') %}
+        <link rel="author" title="{{ _('About these documents') }}"
+              href="{{ pathto('about') }}"/>
+    {%- endif %}
+    {%- if hasdoc('genindex') %}
+        <link rel="index" title="{{ _('Index') }}"
+              href="{{ pathto('genindex') }}"/>
+    {%- endif %}
+    {%- if hasdoc('search') %}
+        <link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}"/>
+    {%- endif %}
+    {%- if hasdoc('copyright') %}
+        <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}"/>
+    {%- endif %}
+    <link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}"/>
+    {%- if parents %}
+        <link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}"/>
+    {%- endif %}
+    {%- if next %}
+        <link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}"/>
+    {%- endif %}
+    {%- if prev %}
+        <link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}"/>
+    {%- endif %}
+  {%- endblock %}
+  {%- block extrahead %} {% endblock %}
+
+  {# Keep modernizr in head - http://modernizr.com/docs/#installing #}
+  <script src="{{ pathto('_static/js/modernizr.min.js', 1) }}"></script>
+
+</head>
+
+<body class="wy-body-for-nav" role="document">
+
+  {% block extrabody %} {% endblock %}
+  <div class="wy-grid-for-nav">
+
+    {# SIDE NAV, TOGGLES ON MOBILE #}
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search">
+          {% block sidebartitle %}
+
+          {% if logo and theme_logo_only %}
+            <a href="{{ pathto(master_doc) }}">
+          {% else %}
+            <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
+          {% endif %}
+
+          {% if logo %}
+            {# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #}
+            <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" />
+          {% endif %}
+          </a>
+
+          {% if theme_display_version %}
+            {%- set nav_version = version %}
+            {% if READTHEDOCS and current_version %}
+              {%- set nav_version = current_version %}
+            {% endif %}
+            {% if nav_version %}
+              <div class="version">
+                {{ nav_version }}
+              </div>
+            {% endif %}
+          {% endif %}
+
+          <a href="/social/en/">EN</a>
+          |
+          <a href="/social/es/">ES</a>
+
+          {% include "searchbox.html" %}
+
+          {% endblock %}
+        </div>
+
+        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+          {% block menu %}
+            {% set toctree = toctree(collapse=theme_collapse_navigation, includehidden=True) %}
+            {% if toctree %}
+                {{ toctree }}
+            {% else %}
+                <!-- Local TOC -->
+                <div class="local-toc">{{ toc }}</div>
+            {% endif %}
+          {% endblock %}
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+
+      {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
+      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
+        {% block mobile_nav %}
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="{{ pathto(master_doc) }}">{{ project }}</a>
+        {% endblock %}
+      </nav>
+
+
+      {# PAGE CONTENT #}
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          {% include "breadcrumbs.html" %}
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+            {% block body %}{% endblock %}
+           </div>
+          </div>
+          {% include "footer.html" %}
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+  {% include "versions.html" %}
+
+  {% if not embedded %}
+
+    <script type="text/javascript">
+        var DOCUMENTATION_OPTIONS = {
+            URL_ROOT:'{{ url_root }}',
+            VERSION:'{{ release|e }}',
+            COLLAPSE_INDEX:false,
+            FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
+            HAS_SOURCE:  {{ has_source|lower }},
+            SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}'
+        };
+    </script>
+    {%- for scriptfile in script_files %}
+      <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
+    {%- endfor %}
+
+  {% endif %}
+
+  {# RTD hosts this file, so just load on non RTD builds #}
+  {% if not READTHEDOCS %}
+    <script type="text/javascript" src="{{ pathto('_static/js/theme.js', 1) }}"></script>
+  {% endif %}
+
+  {# STICKY NAVIGATION #}
+  {% if theme_sticky_navigation %}
+  <script type="text/javascript">
+      jQuery(function () {
+          SphinxRtdTheme.StickyNav.enable();
+      });
+  </script>
+  {% endif %}
+
+  {%- block footer %} {% endblock %}
+
+</body>
+</html>
--- a/docs/conf.py
+++ b/docs/conf.py
@ -54,9 +54,9 @@ author = u'Various contributors'
 # built documents.
 #
 # The short X.Y version.
-version = u'0.1'
+version = u'0.1.2'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1'
+release = u'0.1.2'

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@ -113,15 +113,16 @@ html_theme = 'sphinx_rtd_theme'
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-
+    
 }

 html_context = {
    'show_sphinx': False,
-    'show_copyright': False,
+    'show_copyright': True,
    'show_source': False,
    'build_id': subprocess.check_output(["git", "rev-parse", "--short", "HEAD"]),
-    'build_url': 'https://git.gnu.io/tom/social-doc'
+    'build_url': 'https://git.gnu.io/tom/social-doc',
+    'copyright': "2018 Authors in README. Creative Commons CC-BY-3.0"
 }

 # Add any paths that contain custom themes here, relative to this directory.
@ -295,6 +296,6 @@ texinfo_documents = [
 locale_dirs = ['locale/']
 gettext_compact = False

-
 def setup(app):
-    app.add_stylesheet('css/custom.css')
+    app.add_css_file('css/custom.css')
+
--- a/docs/index.rst
+++ b/docs/index.rst
@ -9,7 +9,7 @@ The Unofficial GNU Social documentation!
 Contents:

 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3

   user/index
   admin/index
--- a/docs/locale/es/LC_MESSAGES/user/tags.po
+++ b/docs/locale/es/LC_MESSAGES/user/tags.po
@ -10,7 +10,7 @@ msgstr ""
 "Project-Id-Version: The Unofficial GNU Social Manuals 0.1\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: 2016-11-06 00:43+0100\n"
-"PO-Revision-Date: 2016-11-20 12:51+0100\n"
+"PO-Revision-Date: 2016-12-13 16:33+0100\n"
 "Last-Translator: drymer <drymer@autistici.org>\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
@ -64,8 +64,8 @@ msgstr ""
 "palabra se convierte en un enlace clicable. Cuando le haces clic se muestran "
 "mensajes de todas las personas que han usado ese hashtag. Permite encontrar "
 "rápidamente otra gente que escribe sobre ese tema o llamar la atención de "
-"quien esté leyendo ese hashtag. Twitter convirtió familiarizó este concepto "
-"y ahora es un elemento básico del microblogging."
+"quien esté leyendo ese hashtag. Twitter familiarizó este concepto y ahora es "
+"un elemento básico del microblogging."

 # f04e29bf7f2a4f23a2967479cb62c641
 #: ../../user/tags.rst:29
--- a/requirements.txt
+++ b/requirements.txt
@ -1,3 +1,3 @@
-Sphinx>=1.3.6
+Sphinx>=4.1.1
 sphinx_rtd_theme
 sphinx-intl
Author	SHA1	Message	Date
Thomas Karpiniec	43d2fbd82e	Update for new sphinx version	2021-07-21 15:26:34 +10:00
Thomas Karpiniec	3ddbc293a6	Rename README.sphinx to enable markdown presentation	2018-08-28 19:59:33 +10:00
Thomas Karpiniec	1b2765cfcb	Add instructions for new pages and internationalisation	2018-08-28 19:57:27 +10:00
Thomas Karpiniec	9552f145e2	Add copyright footer and update READMEs. Fixes #2	2018-03-26 20:09:52 +11:00
Thomas Karpiniec	69d897cf5e	Merge branch 'master' into 'master' Fix typo See merge request !3	2016-12-24 22:28:11 +00:00
drymer	d021f9200a	Fix typo	2016-12-13 16:34:19 +01:00
Thomas Karpiniec	c89cce5767	Increase tocdepth to 3	2016-12-12 20:50:36 +11:00
Thomas Karpiniec	275be54b18	Get my paths write for language links	2016-12-12 20:41:00 +11:00
Thomas Karpiniec	63531aa6a6	Add credit for drymer for translation	2016-12-12 20:39:16 +11:00
Thomas Karpiniec	52a9d97b30	Add language links	2016-12-12 20:37:56 +11:00