Add config to build HTML documentation with Sphinx

.gitignore

@@ -40,6 +40,10 @@ pip-log.txt
 nosetests.xml
 htmlcov/
 
+# Sphinx
+docs/_build/
+docs/modules/
+
 # Translations
 *.mo
 

.readthedocs.yml

@@ -0,0 +1,16 @@
+# Read the Docs configuration file
+version: 2
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+python:
+  version: 3.7
+  system_packages: True
+  # Install packages specified in extras_require['docs'] in setup.py
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/Makefile

@@ -0,0 +1,15 @@
+# Minimal makefile for Sphinx documentation
+# Put help first so that "make" without arguments is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help all clean-apidoc Makefile
+
+all: clean clean-apidoc html
+
+clean-apidoc:
+	rm -rf "./modules"
+
+# Catch-all target: route all unknown targets to Sphinx builder
+%: Makefile
+	sphinx-build -M $@ . _build $(O)

docs/conf.py

@@ -0,0 +1,55 @@
+# Documentation build configuration file
+import sys
+from os.path import abspath, dirname, join
+
+DOCS_DIR = abspath(dirname(__file__))
+PROJECT_DIR = dirname(DOCS_DIR)
+PACKAGE_DIR = join(PROJECT_DIR, 'gpxpy')
+
+# Add project path so we can import our package
+sys.path.insert(0, PROJECT_DIR)
+import gpxpy
+
+# General information about the project.
+project = 'gpxpy'
+copyright = '2020, Tomo Krajina'
+needs_sphinx = '3.0'
+master_doc = 'index'
+source_suffix = ['.rst', '.md']
+version = release = gpxpy.__version__
+html_static_path = ['_static']
+templates_path = ['_templates']
+
+# Exclude the generated gpxpy.rst, which will just contain top-level __init__ info
+exclude_patterns = ['_build', 'modules/gpxpy.rst']
+
+# Sphinx extension modules
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx_autodoc_typehints',
+    'sphinxcontrib.apidoc',
+    'm2r2',
+]
+
+# Enable Numpy-style docstrings
+napoleon_numpy_docstring = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+
+# Use sphinx-apidoc to auto-generate rst sources
+# Configured here instead of instead of in Makefile so it will be used by ReadTheDocs
+apidoc_module_dir = PACKAGE_DIR
+apidoc_output_dir = 'modules'
+apidoc_module_first = True
+apidoc_separate_modules = True
+apidoc_toc_file = False
+
+# Move type hint info to function description instead of signature
+autodoc_typehints = 'description'
+set_type_checking_flag = True
+
+# HTML theme settings
+pygments_style = 'sphinx'
+html_theme = 'sphinx_rtd_theme'

docs/contributing.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../CONTRIBUTING.md

docs/history.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../CHANGELOG.md

docs/index.rst

@@ -0,0 +1,15 @@
+.. _index-page:
+
+.. mdinclude:: ../README.md
+    :start-line: 1
+
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   reference
+   contributing
+   history

docs/reference.rst

@@ -0,0 +1,10 @@
+Reference
+=========
+
+.. Note: Source files for module docs are generated by sphinx-apidoc
+.. toctree::
+    :caption: API Documentation
+    :glob:
+    :titlesonly:
+
+    modules/*

gpxpy/__init__.py

@@ -21,7 +21,7 @@
 def parse(xml_or_file: Union[AnyStr, IO[str]], version: Optional[str] = None) -> mod_gpx.GPX:
     """
     Parse xml (string) or file object. This is just an wrapper for
-    GPXParser.parse() function.
+    :py:meth:`GPXParser.parse`.
 
     parser may be 'lxml', 'minidom' or None (then it will be automatically
     detected, lxml if possible).

gpxpy/gpx.py

@@ -417,7 +417,7 @@ def length(self) -> float:
         """
         Computes length (2-dimensional) of route.
 
-        Returns:
+        Returns
         -----------
         length: float
             Length returned in meters
@@ -934,7 +934,7 @@ def get_time_bounds(self) -> TimeBounds:
         """
         Gets the time bound (start and end) of the segment.
 
-        returns
+        Returns
         ----------
         time_bounds : TimeBounds named tuple
             start_time : datetime

gpxpy/gpxfield.py

@@ -296,8 +296,8 @@ def to_xml(self, value: Any, version: str, nsmap: Optional[Dict[str, str]]=None,
             version: str of the gpx output version "1.0" or "1.1"
 
         Returns:
-            None if value is empty or str of XML representation of the
-            address. Representation starts with a \n.
+            None if value is empty or str of XML representation of the address.
+            Representation starts with ``\\n``.
         """
         if not value:
             return ''

setup.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python
 
-# Copyright 2011 Tomo Krajina
+# Copyright 2020 Tomo Krajina
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -38,6 +38,15 @@
     package_data={"gpxpy": ["py.typed"]},
     packages=['gpxpy', ],
     python_requires=">=3.6",
+    extras_require={
+        'docs': [
+            'm2r2',
+            'Sphinx~=3.2.1',
+            'sphinx-autodoc-typehints',
+            'sphinx-rtd-theme',
+            'sphinxcontrib-apidoc',
+        ],
+    },
     classifiers=[
         "Programming Language :: Python",
         "Programming Language :: Python :: 3.6",