DOC: implement initial documentation layout (#8)

Author: jorgepiloto

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j auto
+SPHINXOPTS    = -j auto -W --color
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build

doc/source/_autoapi_templates/index.rst

@@ -0,0 +1,13 @@
+API reference
+=============
+
+This page contains the ``ansys-geometry-core`` API reference.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages %}
+   {% if page.top_level_object and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}

doc/source/conf.py

@@ -26,6 +26,7 @@
 
 # Sphinx extensions
 extensions = [
+    "autoapi.extension",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "numpydoc",
@@ -55,7 +56,7 @@
 numpydoc_validation_checks = {
     "GL06",  # Found unknown section
     "GL07",  # Sections are in the wrong order.
-    "GL08",  # The object does not have a docstring
+    # "GL08",  # The object does not have a docstring
     "GL09",  # Deprecation warning should precede extended summary
     "GL10",  # reST directives {directives} must be followed by two colons
     "SS01",  # No summary found
@@ -79,3 +80,16 @@
 
 # The master toctree document.
 master_doc = "index"
+
+# Configuration for Sphinx autoapi
+autoapi_type = "python"
+autoapi_dirs = ["../../src/"]
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "special-members",
+]
+autoapi_template_dir = "_autoapi_templates"
+exclude_patterns = ["_autoapi_templates/index.rst"]

doc/source/contributing.rst

@@ -0,0 +1,2 @@
+Contributing
+############

doc/source/examples/index.rst

@@ -0,0 +1,2 @@
+Examples
+########

doc/source/getting_started.rst

@@ -0,0 +1,2 @@
+Getting started
+###############

doc/source/index.rst

@@ -4,3 +4,13 @@
    here.
 
 .. include:: ../../README.rst
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+
+   getting_started
+   user_guide
+   examples/index
+   autoapi/index
+   contributing

doc/source/user_guide.rst

@@ -0,0 +1,2 @@
+User guide
+##########

pyproject.toml

@@ -30,16 +30,17 @@ python = ">=3.7,<4.0"
 importlib-metadata = {version = "^4.0", python = "<3.8"}
 
 # Optional dependencies
-Sphinx = {version = "==5.1.1", optional = true}
-numpydoc = {version = "==1.4.0", optional = true}
 ansys-sphinx-theme = {version = "==0.5.2", optional = true}
-sphinx-copybutton = {version = "==0.5", optional = true}
+numpydoc = {version = "==1.4.0", optional = true}
 pytest = {version = "==7.1.2", optional = true}
 pytest-cov = {version = "==3.0.0", optional = true}
+Sphinx = {version = "==5.1.1", optional = true}
+sphinx-autoapi = {version = "==1.9.0", optional = true}
+sphinx-copybutton = {version = "==0.5", optional = true}
 
 [tool.poetry.extras]
 test = ["pytest","pytest-cov"]
-docs = ["Sphinx", "sphinx-copybutton", "numpydoc", "ansys-sphinx-theme"]
+docs = ["ansys-sphinx-theme", "numpydoc", "Sphinx", "sphinx-autoapi", "sphinx-copybutton"]
 
 [tool.black]
 line-length = 100