-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Readthedocs #25
Readthedocs #25
Changes from 13 commits
96c4e32
0ca75ce
0a22e27
70760b8
0be1790
82acee3
0841b53
d6e0e74
baf2916
83930b2
97d3bd7
791c8d7
949b1b8
049f89d
20db507
a0f44fe
955e57a
517e965
b55bbad
3f8e514
dbb72d1
e11d5a8
e17b676
f1c18b1
2440034
0d17272
d685d58
ff37095
1d3b366
405fd24
d34193b
1eb9439
37469c3
35274c3
385441e
3fa049a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
# .readthedocs.yaml | ||
# Read the Docs configuration file | ||
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details | ||
|
||
# Required | ||
version: 2 | ||
|
||
# Set the version of Python and other tools you might need | ||
build: | ||
os: ubuntu-22.04 | ||
tools: | ||
python: "3.10" | ||
|
||
python: | ||
install: | ||
- requirements: docs/requirements.txt | ||
- method: pip | ||
path: . | ||
extra_requirements: | ||
- docs | ||
# Build documentation in the docs/ directory with Sphinx | ||
sphinx: | ||
configuration: docs/source/conf.py | ||
# fail_on_warning: true | ||
# Optionally build your docs in additional formats such as PDF | ||
formats: | ||
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = source | ||
BUILDDIR = build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=source | ||
set BUILDDIR=build | ||
|
||
if "%1" == "" goto help | ||
|
||
%SPHINXBUILD% >NUL 2>NUL | ||
if errorlevel 9009 ( | ||
echo. | ||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx | ||
echo.installed, then set the SPHINXBUILD environment variable to point | ||
echo.to the full path of the 'sphinx-build' executable. Alternatively you | ||
echo.may add the Sphinx directory to PATH. | ||
echo. | ||
echo.If you don't have Sphinx installed, grab it from | ||
echo.http://sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
sphinx==7.1.2 | ||
sphinx-rtd-theme==1.3.0rc1 | ||
sphinx-collections | ||
sphinxcontrib-bibtex | ||
sphinx_immaterial | ||
sphinx_subfigure | ||
nbsphinx | ||
myst_parser |
Original file line number | Diff line number | Diff line change | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,119 @@ | ||||||||||||||||||||||
# Configuration file for the Sphinx documentation builder. | ||||||||||||||||||||||
import os | ||||||||||||||||||||||
import shutil | ||||||||||||||||||||||
import sys | ||||||||||||||||||||||
from pathlib import Path | ||||||||||||||||||||||
|
||||||||||||||||||||||
# Configuration file for the Sphinx documentation builder. | ||||||||||||||||||||||
# | ||||||||||||||||||||||
# This file only contains a selection of the most common options. For a full | ||||||||||||||||||||||
# list see the documentation: | ||||||||||||||||||||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html | ||||||||||||||||||||||
|
||||||||||||||||||||||
# -- Path setup | ||||||||||||||||||||||
|
||||||||||||||||||||||
__location__ = Path(os.path.dirname(__file__)) | ||||||||||||||||||||||
__src__ = __location__ / "../.." | ||||||||||||||||||||||
|
||||||||||||||||||||||
# 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, str(__src__)) | ||||||||||||||||||||||
|
||||||||||||||||||||||
|
||||||||||||||||||||||
# -- Project information | ||||||||||||||||||||||
|
||||||||||||||||||||||
project = "ESGPTTaskQuerying" | ||||||||||||||||||||||
copyright = "2024, Justin Xu & Matthew McDermott" | ||||||||||||||||||||||
author = "Justin Xu & Matthew McDermott" | ||||||||||||||||||||||
|
||||||||||||||||||||||
release = "0.0.1" | ||||||||||||||||||||||
version = "0.0.1" | ||||||||||||||||||||||
|
||||||||||||||||||||||
|
||||||||||||||||||||||
def ensure_pandoc_installed(_): | ||||||||||||||||||||||
"""Source: https://stackoverflow.com/questions/62398231/building-docs-fails-due-to-missing-pandoc""" | ||||||||||||||||||||||
import pypandoc | ||||||||||||||||||||||
|
||||||||||||||||||||||
# Download pandoc if necessary. If pandoc is already installed and on | ||||||||||||||||||||||
# the PATH, the installed version will be used. Otherwise, we will | ||||||||||||||||||||||
# download a copy of pandoc into docs/bin/ and add that to our PATH. | ||||||||||||||||||||||
pandoc_dir = str(__location__ / "bin") | ||||||||||||||||||||||
# Add dir containing pandoc binary to the PATH environment variable | ||||||||||||||||||||||
if pandoc_dir not in os.environ["PATH"].split(os.pathsep): | ||||||||||||||||||||||
os.environ["PATH"] += os.pathsep + pandoc_dir | ||||||||||||||||||||||
|
||||||||||||||||||||||
pypandoc.ensure_pandoc_installed( | ||||||||||||||||||||||
targetfolder=pandoc_dir, | ||||||||||||||||||||||
delete_installer=True, | ||||||||||||||||||||||
) | ||||||||||||||||||||||
|
||||||||||||||||||||||
|
||||||||||||||||||||||
# -- Run sphinx-apidoc ------------------------------------------------------- | ||||||||||||||||||||||
# This ensures we don't need to run apidoc manually. | ||||||||||||||||||||||
|
||||||||||||||||||||||
# TODO: use https://github.com/sphinx-extensions2/sphinx-autodoc2 | ||||||||||||||||||||||
|
||||||||||||||||||||||
from sphinx.ext import apidoc | ||||||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Move the module-level import to the top of the file to follow Python's best practices. - from sphinx.ext import apidoc
+ # Moved to top Committable suggestion
Suggested change
|
||||||||||||||||||||||
|
||||||||||||||||||||||
output_dir = __location__ / "api" | ||||||||||||||||||||||
module_dir = __src__ / "src/esgpt_task_querying" | ||||||||||||||||||||||
if output_dir.is_dir(): | ||||||||||||||||||||||
shutil.rmtree(output_dir) | ||||||||||||||||||||||
|
||||||||||||||||||||||
try: | ||||||||||||||||||||||
cmd_line = f"--implicit-namespaces -e -f -o {output_dir} {module_dir}" | ||||||||||||||||||||||
apidoc.main(cmd_line.split(" ")) | ||||||||||||||||||||||
except Exception as e: # pylint: disable=broad-except | ||||||||||||||||||||||
print(f"Running `sphinx-apidoc {cmd_line}` failed!\n{e}") | ||||||||||||||||||||||
Comment on lines
+65
to
+69
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Improve error handling by specifying more specific exception types instead of using a broad exception. - except Exception as e: # pylint: disable=broad-except
+ except (SpecificExceptionType1, SpecificExceptionType2) as e: Committable suggestion
Suggested change
|
||||||||||||||||||||||
|
||||||||||||||||||||||
|
||||||||||||||||||||||
# -- General configuration | ||||||||||||||||||||||
|
||||||||||||||||||||||
extensions = [ | ||||||||||||||||||||||
"sphinx.ext.duration", | ||||||||||||||||||||||
"sphinx.ext.doctest", | ||||||||||||||||||||||
"sphinx.ext.autodoc", | ||||||||||||||||||||||
"sphinx.ext.autosummary", | ||||||||||||||||||||||
"sphinx.ext.intersphinx", | ||||||||||||||||||||||
"sphinx.ext.todo", | ||||||||||||||||||||||
"sphinx.ext.viewcode", | ||||||||||||||||||||||
"sphinx.ext.coverage", | ||||||||||||||||||||||
"sphinx.ext.ifconfig", | ||||||||||||||||||||||
"sphinx.ext.mathjax", | ||||||||||||||||||||||
"sphinx.ext.napoleon", | ||||||||||||||||||||||
"sphinxcontrib.bibtex", | ||||||||||||||||||||||
"sphinxcontrib.collections", | ||||||||||||||||||||||
"sphinx_subfigure", | ||||||||||||||||||||||
"sphinx_immaterial", | ||||||||||||||||||||||
"myst_parser", | ||||||||||||||||||||||
"nbsphinx", | ||||||||||||||||||||||
] | ||||||||||||||||||||||
|
||||||||||||||||||||||
collections_dir = __location__ / "_collections" | ||||||||||||||||||||||
if not collections_dir.is_dir(): | ||||||||||||||||||||||
os.mkdir(collections_dir) | ||||||||||||||||||||||
|
||||||||||||||||||||||
intersphinx_mapping = { | ||||||||||||||||||||||
"python": ("https://docs.python.org/3/", None), | ||||||||||||||||||||||
"sphinx": ("https://www.sphinx-doc.org/en/master/", None), | ||||||||||||||||||||||
} | ||||||||||||||||||||||
intersphinx_disabled_domains = ["std"] | ||||||||||||||||||||||
|
||||||||||||||||||||||
templates_path = ["_templates"] | ||||||||||||||||||||||
|
||||||||||||||||||||||
# List of patterns, relative to source directory, that match files and | ||||||||||||||||||||||
# directories to ignore when looking for source files. | ||||||||||||||||||||||
# This pattern also affects html_static_path and html_extra_path. | ||||||||||||||||||||||
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] | ||||||||||||||||||||||
|
||||||||||||||||||||||
# Control options for included jupyter notebooks. | ||||||||||||||||||||||
nb_execution_mode = "off" | ||||||||||||||||||||||
|
||||||||||||||||||||||
# -- Options for HTML output | ||||||||||||||||||||||
|
||||||||||||||||||||||
html_theme = "sphinx_immaterial" | ||||||||||||||||||||||
|
||||||||||||||||||||||
|
||||||||||||||||||||||
# -- Options for EPUB output | ||||||||||||||||||||||
epub_show_urls = "footnote" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ensure clarity in the source comment for
ensure_pandoc_installed
.This change clarifies the purpose of the function directly in the source comment.
Committable suggestion