Skip to content

Commit

Permalink
Move docs to readthedocs (#797)
Browse files Browse the repository at this point in the history
* update config for readthedocs

* remove sphinx-multiversion config

* Clean up config files

* Update gitignore

* update build files
  • Loading branch information
tcmetzger authored Apr 23, 2024
1 parent 950ca44 commit d0a4bc4
Show file tree
Hide file tree
Showing 8 changed files with 64 additions and 114 deletions.
32 changes: 0 additions & 32 deletions .github/workflows/docs-publish.yml

This file was deleted.

1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ share/python-wheels/
*.egg
MANIFEST
xrspatial/.version
xrspatial/_version.py

# PyInstaller
# Usually these files are written by a python script from a template
Expand Down
26 changes: 26 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# .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 OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.12"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/source/conf.py

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- method: pip
path: .
extra_requirements:
- [docs, tests]
28 changes: 12 additions & 16 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -1,24 +1,20 @@
# Makefile for Sphinx documentation
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = python -m sphinx
# 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

.PHONY: help clean html

# Put it first so that "make" without argument is like "make help".
help:
@echo "Please use 'make <target>' where <target> is one of"
@echo " clean to clear all built documentation files"
@echo " html to make all standalone HTML files"
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

clean:
-rm -rf $(BUILDDIR)/*
.PHONY: help Makefile

html: clean
( THEME=sphinx_rtd_theme sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/html )
( THEME=pydata_sphinx_theme sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/html )
# 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)
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
42 changes: 17 additions & 25 deletions docs/make.bat
Original file line number Diff line number Diff line change
Expand Up @@ -10,34 +10,26 @@ if "%SPHINXBUILD%" == "" (
set SOURCEDIR=source
set BUILDDIR=build

if "%1" == "" goto help

if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. clean to clear all built documentation files
echo. html to make all standalone HTML files

goto end
)

if "%1" == "clean" (
rmdir %BUILDDIR% /s /q
goto end
%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.https://www.sphinx-doc.org/
exit /b 1
)

if "%1" == "html" (
set THEME=sphinx_rtd_theme
sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html
if "%1" == "" goto help

set THEME=pydata_sphinx_theme
sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
26 changes: 7 additions & 19 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

# -- Path setup --------------------------------------------------------------

from datetime import datetime
import json
# 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
Expand All @@ -23,7 +24,7 @@
# -- Project information -----------------------------------------------------

project = u'xarray_spatial'
copyright = u'2020-2022, makepath'
copyright = u'2020-{}, makepath'.format(datetime.now().year)
author = u'makepath'

version = release = xrspatial.__version__
Expand Down Expand Up @@ -66,7 +67,7 @@
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
language = 'en'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
Expand All @@ -82,38 +83,26 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
if os.getenv('THEME') == 'sphinx_rtd_theme':
html_theme = 'sphinx_rtd_theme'
else:
html_theme = 'pydata_sphinx_theme'

html_theme = 'pydata_sphinx_theme'

html_logo = '_static/img/Xarray-Spatial-logo.svg'

html_favicon = '_static/img/favicon.ico'

# sphinx-multiversion config
smv_branch_whitelist = 'master'
if os.getenv('THEME') == 'sphinx_rtd_theme':
smv_tag_whitelist = r'^v([0-9]\.[2-9]\.[0-9])'
else:
smv_tag_whitelist = r'^v([0-9]\.[2-9]\.[0-9])'

# Load releases
with open("releases.json") as f:
releases = json.load(f)

# 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
# documentation.
#
html_theme_options = {
"external_links": [],
"github_url": "https://github.com/makepath/xarray-spatial",
"navbar_end": ["navbar-icon-links"],
}

html_context = {
'css_files': ['_static/css/styles.css'],
'releases': [(release, url) for release, url in releases.items()],
"default_mode": "light",
}

autosummary_generate = True
Expand All @@ -133,7 +122,6 @@
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}


# -- Options for HTMLHelp output ---------------------------------------------
Expand Down
21 changes: 0 additions & 21 deletions docs/source/releases.json

This file was deleted.

2 changes: 1 addition & 1 deletion setup.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ console_scripts =

[options.extras_require]
doc =
dask[dataframe]
geopandas
Jinja2 >=2.11
ipykernel
Expand All @@ -43,7 +44,6 @@ doc =
pandoc
pydata_sphinx_theme
sphinx
sphinx-multiversion
sphinx-panels
sphinx_rtd_theme
examples =
Expand Down

0 comments on commit d0a4bc4

Please sign in to comment.