Skip to content

Commit 5bc10c5

Browse files
gassmoellergassmoeller
authored
Merge pull request #4 from ljhwang/sphinx_revised
Adds a template for sphinx documentation
2 parents 8dae6e2 + 3c775d7 commit 5bc10c5

22 files changed

+470
-1
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
doc/sphinx_template/notebooks
2+
doc/sphinx_template/_build
3+
.DS_Store

‎.readthedocs.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# .readthedocs.yml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
build:
9+
os: "ubuntu-22.04"
10+
tools:
11+
python: "mambaforge-4.10"
12+
13+
# Build documentation in the root directory with Sphinx
14+
sphinx:
15+
configuration: ./doc/sphinx_template/docs/conf.py
16+
17+
# Optionally build your docs in additional formats such as PDF and ePub
18+
formats:
19+
- htmlzip
20+
- pdf
21+
22+
conda:
23+
environment: ./doc/sphinx/environment.yml

‎doc/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
This directory should contain the documentation for your software. For the
2-
official manual template provided by the Computational Infrastructure for
2+
official manual template in tex provided by the Computational Infrastructure for
33
Geodynamics, see:
44
https://github.com/geodynamics/best_practices/tree/master/software_manual_template
55

6+
To generate html documentation using sphinx, see the directory /sphinx_template.
7+
Navigate to sphinx_template/docs/_build/html and double click on index.html to access
8+
instructions on how to use the template and to view the example.
9+
610
Keep in mind that your code should ideally also use an in-source documentation
711
system like doxygen or autodoc. We recommend writing your manual in LaTeX (like
812
the template linked above), Markdown, or reStructuredText.

‎doc/notebooks/helloworld.ipynb‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {
6+
"id": "gwO_-sC1nHY3"
7+
},
8+
"source": [
9+
"# Notebooks #\n",
10+
"This is a simple placeholder notebook that is embedded into the documentation."
11+
]
12+
},
13+
{
14+
"cell_type": "code",
15+
"execution_count": 1,
16+
"metadata": {
17+
"colab": {
18+
"base_uri": "https://localhost:8080/"
19+
},
20+
"id": "x5TShbFCnHY5",
21+
"outputId": "f765e3c8-90a9-4d9f-a08d-f5edd840c2c8"
22+
},
23+
"outputs": [
24+
{
25+
"output_type": "stream",
26+
"name": "stdout",
27+
"text": [
28+
"Hello World\n"
29+
]
30+
}
31+
],
32+
"source": [
33+
"print(\"Hello World\")"
34+
]
35+
}
36+
],
37+
"metadata": {
38+
"kernelspec": {
39+
"display_name": "Python 3",
40+
"language": "python",
41+
"name": "python3"
42+
},
43+
"language_info": {
44+
"codemirror_mode": {
45+
"name": "ipython",
46+
"version": 3
47+
},
48+
"file_extension": ".py",
49+
"mimetype": "text/x-python",
50+
"name": "python",
51+
"nbconvert_exporter": "python",
52+
"pygments_lexer": "ipython3",
53+
"version": "3.9.6"
54+
},
55+
"orig_nbformat": 4,
56+
"vscode": {
57+
"interpreter": {
58+
"hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
59+
}
60+
},
61+
"colab": {
62+
"provenance": []
63+
}
64+
},
65+
"nbformat": 4,
66+
"nbformat_minor": 0
67+
}

‎doc/sphinx_template/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/sphinx_template/_static/cig_banner_logo.png‎

197 KB
Loading

‎doc/sphinx_template/_static/cig_logo_dots.png‎

19.7 KB
Loading

‎doc/sphinx_template/_templates/navbar_end.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<img src="/en/latest/_static/images/cig_logo_dots.png" alt="CIG Logo" height="80px" style="padding: 5px;"/>

‎doc/sphinx_template/conf.py‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
# Current versions:
3+
# sphinx 4.2.0
4+
# sphinxx-book-theme 1.0.1
5+
# python 3.9.7
6+
# myst-parser 0.18.1
7+
# nbsphinx 0.9.2
8+
# sphinxcontrib-bibtex 2.5.0
9+
#
10+
# This file only contains a selection of the most common options. For a full
11+
# list see the documentation:
12+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
13+
14+
# If you are using notebooks, copy the latest versions into the docs directory so you do not have to
15+
# keep multiple copies.
16+
import shutil
17+
nbdir = '../notebooks'
18+
docdir = './notebooks'
19+
20+
try:
21+
shutil.copytree(nbdir,docdir)
22+
except FileExistsError:
23+
shutil.rmtree(docdir)
24+
shutil.copytree(nbdir,docdir)
25+
26+
# -- Path setup --------------------------------------------------------------
27+
28+
# If extensions (or modules to document with autodoc) are in another directory,
29+
# add these directories to sys.path here. If the directory is relative to the
30+
# documentation root, use os.path.abspath to make it absolute, like shown here.
31+
#
32+
import os
33+
import sys
34+
sys.path.insert(0, os.path.abspath('..'))
35+
36+
# -- Project information -----------------------------------------------------
37+
# This template is derived from the projects GDMATE, ASPECT, and Rayleigh
38+
project = 'Manual Template'
39+
copyright = '2023 Computational Infrastructure for Geodynamics'
40+
author = 'Lorraine J. Hwang'
41+
42+
43+
# -- General configuration ---------------------------------------------------
44+
45+
# Add any Sphinx extension module names here, as strings. They can be
46+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
47+
# ones.
48+
extensions = [
49+
"nbsphinx",
50+
"sphinx.ext.autodoc",
51+
"sphinx.ext.autosummary",
52+
"sphinxcontrib.bibtex",
53+
"myst_parser"
54+
]
55+
56+
autosummary_imported_members = True
57+
58+
# Add any paths that contain templates here, relative to this directory.
59+
templates_path = ['_templates']
60+
61+
# List of patterns, relative to source directory, that match files and
62+
# directories to ignore when looking for source files.
63+
# This pattern also affects html_static_path and html_extra_path.
64+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
65+
nbsphinx_allow_errors = True
66+
nbsphinx_execute = 'never'
67+
68+
# -- Options for HTML output -------------------------------------------------
69+
70+
# The theme to use for HTML and HTML Help pages. See the documentation for
71+
# a list of builtin themes.
72+
#
73+
74+
html_theme = 'sphinx_book_theme'
75+
html_theme_options = {
76+
"collapse_navigation": True,
77+
"navigation_depth": 3,
78+
"show_toc_level": 3,
79+
"repository_url": "https://github.com/geodynamics/software_template/",
80+
"repository_branch": "main",
81+
"path_to_docs":".",
82+
"icon_links": [
83+
{
84+
"name": "GitHub",
85+
"url": "https://github.com/geodynamics/software_template/",
86+
"icon": "fab fa-github-square",
87+
},
88+
],
89+
"show_navbar_depth": 1,
90+
"use_repository_button": True,
91+
"use_edit_page_button": True,
92+
"use_issues_button": True,
93+
"logo": {
94+
"text": "My Project Title",
95+
96+
},
97+
"home_page_in_toc": True,
98+
"primary_sidebar_end": "navbar_end.html",
99+
}
100+
101+
html_logo = "_static/cig_logo_dots.png"
102+
103+
# Add any paths that contain custom static files (such as style sheets) here,
104+
# relative to this directory. They are copied after the builtin static files,
105+
# so a file named "default.css" will overwrite the builtin "default.css".
106+
html_static_path = ['_static']
107+
108+
109+
# Add bibtex and generate a bibliography
110+
bibtex_bibfiles = ["references.bib"]
111+
bibtex_default_style = "alpha"
112+
bibtex_reference_style = "author_year"
113+
114+
# If true, figures, tables and code-blocks are automatically numbered if they have a caption.
115+
numfig = True

‎doc/sphinx_template/environment.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
name: software_template
2+
channels:
3+
- conda-forge
4+
- defaults
5+
dependencies:
6+
- sphinx-book-theme=1.0.1
7+
- python=3.9.7
8+
- myst-parser=0.18.1
9+
- nbsphinx=0.9.2
10+
- sphinxcontrib-bibtex=2.5.0

0 commit comments

Comments
 (0)