Merge branch 'doc' into 'master'

Build doc automatically, for several version See merge request Oslandia/py3dtiles!81
PermafrostDiscoveryGateway · Jul 3, 2020 · 39fdfba · 39fdfba
2 parents ffde5f1 + deacf63
commit 39fdfba
Show file tree

Hide file tree

Showing 10 changed files with 123 additions and 43 deletions.
diff --git a/.gitignore b/.gitignore
@@ -88,3 +88,4 @@ ENV/
 # Rope project settings
 .ropeproject
 .pytest
+public
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -7,7 +7,7 @@
     - pip install .
     - pip install .[dev]
     - pytest
-    - flake8 setup.py py3dtiles/
+    - flake8 setup.py py3dtiles/ docs/
     # TODO move that in unit tests
     - py3dtiles info tests/pointCloudRGB.pnts
   tags:
@@ -27,3 +27,25 @@ test:python-latest:
 test:python-stretch:
   <<: *job_definition
   image: python:3.7-stretch
+
+#########
+# PAGES #
+#########
+pages:
+  stage: deploy
+  image: python:latest
+  script:
+    - pip install .
+    - pip install .[doc]
+    # sphinx-multiversion needs to have all the branches
+    - git remote add upstream https://gitlab.com/Oslandia/py3dtiles.git
+    - git fetch upstream
+    - sphinx-multiversion docs public
+    - cp -rv docs/index_redirect.html public/index.html
+    - current_version="$(git tag --list | tail -n1)"
+    - sed -i "s/VERSION/$current_version/g" public/index.html
+  artifacts:
+    paths:
+      - public
+  only:
+    - master
diff --git a/README.rst b/README.rst
@@ -24,6 +24,6 @@ p3dtiles is a Python tool and library for manipulating `3D Tiles`_.
 
 py3dtiles is distributed under the Apache 2 Licence.
 
-GitHub repository: https://github.com/Oslandia/py3dtiles
+Gitlab repository: https://gitlab.com/Oslandia/py3dtiles
 
-Documentation : https://oslandia.github.io/py3dtiles
+Documentation : https://oslandia.gitlab.io/py3dtiles
diff --git a/docs/README.md b/docs/README.md
@@ -15,9 +15,15 @@ SPHINX_APIDOC_OPTIONS="members,show-inheritance" sphinx-apidoc -o ./api ../py3dt
 ```
 This command needs to be used only when new files are added (TODO check if sphinx-autoapi wouldn't do this job for us?)
 
-To regenerate the doc:
+To regenerate the doc for one version:
 
 ```
 make clean && make html
 ```
 (For some reason, make clean is often necessary if the toctree changes)
+
+To generate the doc as gitlab does it:
+
+```
+sphinx-multiversion . <outfolder>
+```
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -7,18 +7,33 @@
   {%- set titlesuffix = "" %}
 {%- endif %}
 {%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %}
+{%- set sphinx_writer = 'writer-html5' if html5_doctype else 'writer-html4' %}
 
 <!DOCTYPE html>
-<!--[if IE 8]><html class="no-js lt-ie9" lang="{{ lang_attr }}" > <![endif]-->
-<!--[if gt IE 8]><!--> <html class="no-js" lang="{{ lang_attr }}" > <!--<![endif]-->
+<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
 <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>
+  <title>{{ title|striptags|e }} - {{ current_version.name }}</title>
   {% endblock %}
 
+  {# CSS #}
+  <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
+  <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
+  {%- for css in css_files %}
+    {%- if css|attr("rel") %}
+  <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
+    {%- else %}
+  <link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
+    {%- endif %}
+  {%- endfor %}
+
+  {%- for cssfile in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {%- endfor %}
+
   {# FAVICON #}
   {% if favicon %}
     <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
@@ -29,7 +44,10 @@
   {% endif %}
 
   {# JAVASCRIPTS #}
-  <script type="text/javascript" src="{{ pathto('_static/js/modernizr.min.js', 1) }}"></script>
+  {%- block scripts %}
+  <!--[if lt IE 9]>
+    <script src="{{ pathto('_static/js/html5shiv.min.js', 1) }}"></script>
+  <![endif]-->
   {%- if not embedded %}
   {# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #}
     {% if sphinx_version >= "1.8.0" %}
@@ -62,21 +80,7 @@
           href="{{ pathto('_static/opensearch.xml', 1) }}"/>
     {%- endif %}
   {%- endif %}
-
-  {# CSS #}
-  <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
-  <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
-  {%- for css in css_files %}
-    {%- if css|attr("rel") %}
-  <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
-    {%- else %}
-  <link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
-    {%- endif %}
-  {%- endfor %}
-
-  {%- for cssfile in extra_css_files %}
-    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
-  {%- endfor %}
+  {%- endblock %}
 
   {%- block linktags %}
     {%- if hasdoc('about') %}
@@ -114,21 +118,21 @@
           {% if logo and theme_logo_only %}
             <a href="{{ pathto(master_doc) }}">
           {% else %}
-            <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
+            <a href="{{ pathto(master_doc) }}" class="icon icon-home" alt="{{ _("Documentation 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" alt="Logo"/>
+            <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
           {% endif %}
           </a>
 
           {% if theme_display_version %}
             {%- set nav_version = version %}
             {% if current_version %}
-              {%- set nav_version = current_version %}
+              {%- set nav_version = current_version.name %}
             {% endif %}
             {% if nav_version %}
               <div class="version">
@@ -142,6 +146,7 @@
           {% endblock %}
         </div>
 
+        {% block navigation %}
         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
           {% block menu %}
             {#
@@ -162,13 +167,14 @@
             {% endif %}
           {% endblock %}
         </div>
+        {% endblock %}
         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
           <p class="caption"><span class="caption-text">Links:</span></p>
           <ul>
             <li class="toctree-l1">
-              <a class="reference" href="https://github.com/oslandia/py3dtiles">
-                <span class="fa fa-lg fa-github" />
-                Github Repository
+              <a class="reference" href="https://gitlab.com/oslandia/py3dtiles">
+                <span class="fa fa-lg fa-gitlab" />
+                Gitlab Repository
               </a>
             </li>
           </ul>

diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html
@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,23 +12,13 @@
 # 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.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 
 # -- Project information -----------------------------------------------------
 
 project = u'py3dtiles'
 copyright = u'2019, Augustin Trancart, Paul Blottière, Jérémy Gaillard, Ludovic Delauné, Nicolas Saul, Pierre-Éric Pelloux-Prayer, Raphaël Delhome, Vincent Jaillot, Éric Lemoine'
 author = u'Augustin Trancart, Paul Blottière, Jérémy Gaillard, Ludovic Delauné, Nicolas Saul, Pierre-Éric Pelloux-Prayer, Raphaël Delhome, Vincent Jaillot, Éric Lemoine'
 
-# The short X.Y version
-version = u'master'
-# The full version, including alpha/beta/rc tags
-release = u'1.0.2, 1.0.1, 0.0.9'
-
-
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -46,8 +36,8 @@
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',
     'sphinx_rtd_theme',
+    "sphinx_multiversion",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -106,8 +96,26 @@
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
-# html_sidebars = {}
+# -- Options for sphinx-multiversion
+
+# Whitelist pattern for tags (set to None to ignore all tags)
+smv_tag_whitelist = r'^.*$'
+
+# Whitelist pattern for branches (set to None to ignore all branches)
+smv_branch_whitelist = r'^master$'
+
+# Whitelist pattern for remotes (set to None to use local branches only)
+# set to upstream because we add this remote for gitlab, see .gitlab-ci.yml
+smv_remote_whitelist = r'^upstream|origin$'
+
+# Pattern for released versions
+smv_released_pattern = r'^tags/.*$'
+
+# Format for versioned output directories inside the build directory
+smv_outputdir_format = '{ref.name}'
 
+# Determines whether remote or local git branches/tags are preferred if their output dirs conflict
+smv_prefer_remote_refs = True
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

diff --git a/docs/index_redirect.html b/docs/index_redirect.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to VERSION/</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; URL=VERSION">
+    <link rel="canonical" href="VERSION/index.html">
+  </head>
+</html>
diff --git a/docs/install.rst b/docs/install.rst
@@ -24,7 +24,7 @@ To use py3dtiles from sources:
 .. code-block:: shell
 
     $ apt install git python3 python3-pip virtualenv libopenblas-base liblas-c3
-    $ git clone https://github.com/Oslandia/py3dtiles
+    $ git clone git@gitlab.com:Oslandia/py3dtiles.git
     $ cd py3dtiles
     $ virtualenv -p python3 venv
     $ . venv/bin/activate

diff --git a/setup.py b/setup.py
@@ -29,6 +29,7 @@
 doc_requirements = (
     'sphinx',
     'sphinx_rtd_theme',
+    'sphinx-multiversion',
 )
 
 
@@ -59,7 +60,7 @@ def find_version(*file_paths):
     version=find_version('py3dtiles', '__init__.py'),
     description="Python module for 3D tiles format",
     long_description=read('README.rst'),
-    url='https://github.com/Oslandia/py3dtiles',
+    url='https://gitlab.com/Oslandia/py3dtiles',
     author='Oslandia',
     author_email='contact@oslandia.com',
     license='Apache License Version 2.0',