Redesign documentations

ci/azure-pipelines-linux.yml

@@ -21,7 +21,7 @@ steps:
     set -x -e
     sudo apt-get install -y --no-install-recommends --no-install-suggests \
         python3-pip python3-setuptools python3-wheel graphicsmagick ffmpeg
-    pip3 install --user sphinx
+    pip3 install --user sphinx==1.8.5
     echo "##vso[task.prependpath]$HOME/.local/bin"
   displayName: Install dependencies for building documentation
   condition: eq(variables['BUILD_DOCS'], true)

doc/rst/CMakeLists.txt

@@ -37,6 +37,12 @@ if (SPHINX_FOUND)
 		${CMAKE_CURRENT_BINARY_DIR}/_themes)
 	add_depend_to_target (docs_html_depends _docs_copy_rst_tree_themes)
 	add_depend_to_target (docs_man_depends _docs_copy_rst_tree_themes)
+	copy_dir_if_different (_docs_copy_rst_tree_static
+		${CMAKE_CURRENT_SOURCE_DIR}/_static/
+		${CMAKE_CURRENT_BINARY_DIR}/_static)
+	add_depend_to_target (docs_html_depends _docs_copy_rst_tree_static)
+	add_depend_to_target (docs_pdf_depends _docs_copy_rst_tree_static)
+	add_depend_to_target (docs_man_depends _docs_copy_rst_tree_static)
 	add_custom_target (_docs_rst_mkdir_verbatim
 		COMMAND ${CMAKE_COMMAND} -E make_directory
 		${CMAKE_CURRENT_BINARY_DIR}/_source/_verbatim

doc/rst/_static/style.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 1000px;
+}

doc/rst/conf.py.in

@@ -3,20 +3,16 @@
 # GMT documentation build configuration file, created by
 # sphinx-quickstart on Fri May 04 18:10:30 2012.
 #
-# This file is execfile()d with the current directory set to its containing dir.
-#
 # Note that not all possible configuration values are present in this
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-
-import sys, os
-
+#
 # 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.
-#sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -34,26 +30,20 @@ templates_path = ['_templates']
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-gmt_team = u'The GMT Team'
-project = u'GMT'
-copyright = u' '.join(['@GMT_VERSION_YEAR@,', gmt_team])
+project = 'GMT'
+gmt_team = 'The GMT Team'
+copyright = "@GMT_VERSION_YEAR@, {}.".format(gmt_team)
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '@GMT_PACKAGE_VERSION@'
-# The full version, including alpha/beta/rc tags.
-release = '@GMT_PACKAGE_VERSION_WITH_GIT_REVISION@'
-if tags.has('tex'):
-  release = release.replace("_", "\\_")
+# The version shown in the left sidebar.
+version = '@GMT_PACKAGE_VERSION_MAJOR@.@GMT_PACKAGE_VERSION_MINOR@'
+# The full version shown in the page title
+release = '@GMT_PACKAGE_VERSION@'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -101,6 +91,37 @@ smartquotes_action = 'qe'
 #html_theme = 'default'
 html_theme = 'rtd'
 html_theme_path = ["_themes"]
+html_context = {
+    "menu_links": [
+        (
+            '<i class="fa fa-users fa-fw"></i> Contributing',
+            "https://github.com/GenericMappingTools/gmt/blob/master/CONTRIBUTING.md",
+        ),
+        (
+            '<i class="fa fa-gavel fa-fw"></i> Code of Conduct',
+            "https://github.com/GenericMappingTools/gmt/blob/master/CODE_OF_CONDUCT.md",
+        ),
+        (
+            '<i class="fa fa-book fa-fw"></i> License',
+            "https://github.com/GenericMappingTools/gmt/blob/master/LICENSE.TXT",
+        ),
+        (
+            '<i class="fa fa-comment fa-fw"></i> Contact',
+            "https://gitter.im/GenericMappingTools/Lobby",
+        ),
+        (
+            '<i class="fa fa-github fa-fw"></i> Source Code',
+            "https://github.com/GenericMappingTools/gmt",
+        ),
+    ],
+    # Show the "Edit on Github" link
+    "display_github": True,
+    "github_user": "GenericMappingTools",
+    "github_repo": "gmt",
+    "github_version": version,
+    "conf_py_path": "/doc/rst/source/"
+}
+
 
 # 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
@@ -124,13 +145,13 @@ html_theme_path = ["_themes"]
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = "_static/favicon.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # We set html_static below so that sphinx copies video files to html/_static
-html_static_path = ['_source/_static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -176,55 +197,18 @@ html_show_sourcelink = True
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 
+
+# Load the custom CSS files (needs sphinx >= 1.6 for this to work)
+def setup(app):
+    app.add_stylesheet("style.css")
+
+
 # Redefine supported_image_types for the HTML builder
 from sphinx.builders.html import StandaloneHTMLBuilder
 StandaloneHTMLBuilder.supported_image_types = [
   'image/gif', 'image/jpeg', 'image/png', 'image/svg+xml'
 ]
 
-# -- Options for LaTeX output --------------------------------------------------
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-  ('GMT_Docs',  'GMT_Docs.tex',     u'GMT Documentation',     gmt_team, 'manual'),
-  ('GMT_Tutorial',   'GMT_Tutorial.tex',      u'GMT Tutorial', gmt_team, 'manual'),
-  ('GMT_API',   'GMT_API.tex',      u'GMT API Documentation', gmt_team, 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-latex_logo = '@CMAKE_CURRENT_BINARY_DIR@/_source/_images/GMT_coverlogo.pdf'
-
-# LaTeX preamble
-tex_preamble = r"""
-\frenchspacing % use a standard word space between sentences
-\fvset{fontsize=\scriptsize} % verbatim font size
-"""
-
-# The paper size ('a4paper' or 'letterpaper') and font size.
-latex_elements = {
-    'papersize':'a4paper',
-    'pointsize':'11pt',
-    'preamble': tex_preamble}
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
 # -- Options for manual page output --------------------------------------------
 
 # One entry per manual page. List of tuples
@@ -381,3 +365,5 @@ man_pages = [
 ('supplements/x2sys/x2sys_report', 'x2sys_report', 'Report statistics from crossover data base', '', 1),
 ('supplements/x2sys/x2sys_solve', 'x2sys_solve', 'Determine least-squares systematic correction from crossovers', '', 1)
 ]
+
+