Skip to content

Commit 0f5ee70

Browse files
consideRatioconsideRatio
authored
Merge pull request #1197 from consideRatio/pr/docs-refresh
docs: add devenv, linkcheck, and refresh misc config etc
2 parents 68a0331 + 2dba862 commit 0f5ee70

File tree

12 files changed

+354
-209
lines changed

12 files changed

+354
-209
lines changed

‎.gitignore

Lines changed: 168 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,15 @@
1+
# Manually added parts to .gitignore
2+
# ----------------------------------
3+
#
14
.#*
2-
dist
3-
build
45
*.tar.gz
5-
*.egg-info
66
*.py[co]
7-
__pycache__
8-
MANIFEST
97

108
.DS_Store
11-
.cache
12-
.pytest_cache
13-
.coverage
14-
htmlcov
159

1610
repo2docker/s2i
1711

1812
^bin/
19-
lib/
20-
lib64/
2113
share/
2214
include/
2315

@@ -31,7 +23,171 @@ tests/dockerfile/legacy/root.frozen.yml
3123
generated/
3224
test_file_text.txt
3325

34-
3526
\.vscode/
3627

3728
tests/dockerfile_diff.sh
29+
30+
31+
# Python .gitignore from https://github.com/github/gitignore/blob/HEAD/Python.gitignore
32+
# -------------------------------------------------------------------------------------
33+
#
34+
# Byte-compiled / optimized / DLL files
35+
__pycache__/
36+
*.py[cod]
37+
*$py.class
38+
39+
# C extensions
40+
*.so
41+
42+
# Distribution / packaging
43+
.Python
44+
build/
45+
develop-eggs/
46+
dist/
47+
downloads/
48+
eggs/
49+
.eggs/
50+
lib/
51+
lib64/
52+
parts/
53+
sdist/
54+
var/
55+
wheels/
56+
share/python-wheels/
57+
*.egg-info/
58+
.installed.cfg
59+
*.egg
60+
MANIFEST
61+
62+
# PyInstaller
63+
# Usually these files are written by a python script from a template
64+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
65+
*.manifest
66+
*.spec
67+
68+
# Installer logs
69+
pip-log.txt
70+
pip-delete-this-directory.txt
71+
72+
# Unit test / coverage reports
73+
htmlcov/
74+
.tox/
75+
.nox/
76+
.coverage
77+
.coverage.*
78+
.cache
79+
nosetests.xml
80+
coverage.xml
81+
*.cover
82+
*.py,cover
83+
.hypothesis/
84+
.pytest_cache/
85+
cover/
86+
87+
# Translations
88+
*.mo
89+
*.pot
90+
91+
# Django stuff:
92+
*.log
93+
local_settings.py
94+
db.sqlite3
95+
db.sqlite3-journal
96+
97+
# Flask stuff:
98+
instance/
99+
.webassets-cache
100+
101+
# Scrapy stuff:
102+
.scrapy
103+
104+
# Sphinx documentation
105+
docs/_build/
106+
107+
# PyBuilder
108+
.pybuilder/
109+
target/
110+
111+
# Jupyter Notebook
112+
.ipynb_checkpoints
113+
114+
# IPython
115+
profile_default/
116+
ipython_config.py
117+
118+
# pyenv
119+
# For a library or package, you might want to ignore these files since the code is
120+
# intended to run in multiple environments; otherwise, check them in:
121+
# .python-version
122+
123+
# pipenv
124+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
125+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
126+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
127+
# install all needed dependencies.
128+
#Pipfile.lock
129+
130+
# poetry
131+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
132+
# This is especially recommended for binary packages to ensure reproducibility, and is more
133+
# commonly ignored for libraries.
134+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
135+
#poetry.lock
136+
137+
# pdm
138+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
139+
#pdm.lock
140+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
141+
# in version control.
142+
# https://pdm.fming.dev/#use-with-ide
143+
.pdm.toml
144+
145+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
146+
__pypackages__/
147+
148+
# Celery stuff
149+
celerybeat-schedule
150+
celerybeat.pid
151+
152+
# SageMath parsed files
153+
*.sage.py
154+
155+
# Environments
156+
.env
157+
.venv
158+
env/
159+
venv/
160+
ENV/
161+
env.bak/
162+
venv.bak/
163+
164+
# Spyder project settings
165+
.spyderproject
166+
.spyproject
167+
168+
# Rope project settings
169+
.ropeproject
170+
171+
# mkdocs documentation
172+
/site
173+
174+
# mypy
175+
.mypy_cache/
176+
.dmypy.json
177+
dmypy.json
178+
179+
# Pyre type checker
180+
.pyre/
181+
182+
# pytype static type analyzer
183+
.pytype/
184+
185+
# Cython debug symbols
186+
cython_debug/
187+
188+
# PyCharm
189+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
190+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
191+
# and can be added to the global gitignore or merged into this file. For a more nuclear
192+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
193+
#.idea/

‎.gitpod.yml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
tasks:
22
- init: |
33
pip3 install sphinx-autobuild
4-
pip3 install -r docs/doc-requirements.txt
5-
pip3 install -e.
4+
pip3 install -r docs/requirements.txt
5+
pip3 install -e .
66
command: |
7-
sphinx-autobuild docs/source/ docs/build/html/
7+
sphinx-autobuild docs/source/ docs/_build/html/
88
name: Sphinx preview
99
ports:
10-
- port: 8000
10+
- port: 8000

‎.readthedocs.yaml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Configuration on how ReadTheDocs (RTD) builds our documentation
2+
# ref: https://readthedocs.org/projects/repo2docker-service/
3+
# ref: https://docs.readthedocs.io/en/stable/config-file/v2.html
4+
#
5+
version: 2
6+
7+
sphinx:
8+
configuration: docs/source/conf.py
9+
10+
build:
11+
os: ubuntu-22.04
12+
tools:
13+
python: "3.10"
14+
15+
python:
16+
install:
17+
- requirements: docs/requirements.txt
18+
- method: pip
19+
path: .

‎docs/Makefile

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,38 @@
1-
# Minimal makefile for Sphinx documentation
2-
#
1+
# Makefile for Sphinx documentation generated by sphinx-quickstart
2+
# ----------------------------------------------------------------------------
33

4-
# You can set these variables from the command line.
5-
SPHINXOPTS = -W
6-
SPHINXBUILD = python3 -msphinx
7-
SPHINXPROJ = repo2docker
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
88
SOURCEDIR = source
9-
BUILDDIR = build
9+
BUILDDIR = _build
1010

1111
# Put it first so that "make" without argument is like "make help".
1212
help:
13-
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
1414

1515
.PHONY: help Makefile
1616

1717
# Catch-all target: route all unknown targets to Sphinx using the new
18-
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
# "make mode" option.
1919
%: Makefile
20-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
21+
22+
23+
# Manually added commands
24+
# ----------------------------------------------------------------------------
25+
26+
# For local development:
27+
# - builds and rebuilds html on changes to source
28+
# - starts a livereload enabled webserver and opens up a browser
29+
devenv:
30+
sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
31+
32+
# For local development and CI:
33+
# - verifies that links are valid
34+
linkcheck:
35+
$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
36+
@echo
37+
@echo "Link check complete; look for any errors in the above output " \
38+
"or in $(BUILDDIR)/linkcheck/output.txt."

‎docs/doc-requirements.txt

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/make.bat

Lines changed: 31 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,32 +5,51 @@ pushd %~dp0
55
REM Command file for Sphinx documentation
66

77
if "%SPHINXBUILD%" == "" (
8-
set SPHINXBUILD=python -msphinx
8+
set SPHINXBUILD=sphinx-build
99
)
1010
set SOURCEDIR=source
11-
set BUILDDIR=build
12-
set SPHINXPROJ=repo2docker
11+
set BUILDDIR=_build
1312

1413
if "%1" == "" goto help
14+
if "%1" == "devenv" goto devenv
15+
if "%1" == "linkcheck" goto linkcheck
16+
goto default
1517

18+
19+
:default
1620
%SPHINXBUILD% >NUL 2>NUL
1721
if errorlevel 9009 (
1822
echo.
19-
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
20-
echo.then set the SPHINXBUILD environment variable to point to the full
21-
echo.path of the 'sphinx-build' executable. Alternatively you may add the
22-
echo.Sphinx directory to PATH.
23+
echo.The 'sphinx-build' command was not found. Open and read README.md!
24+
exit /b 1
25+
)
26+
%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
27+
goto end
28+
29+
30+
:help
31+
%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
32+
goto end
33+
34+
35+
:devenv
36+
sphinx-autobuild >NUL 2>NUL
37+
if errorlevel 9009 (
2338
echo.
24-
echo.If you don't have Sphinx installed, grab it from
25-
echo.http://sphinx-doc.org/
39+
echo.The 'sphinx-autobuild' command was not found. Open and read README.md!
2640
exit /b 1
2741
)
42+
sphinx-autobuild -b html --open-browser "%SOURCEDIR%" "%BUILDDIR%/html" %SPHINXOPTS%
43+
goto end
44+
2845

29-
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
46+
:linkcheck
47+
%SPHINXBUILD% -b linkcheck "%SOURCEDIR%" "%BUILDDIR%/linkcheck" %SPHINXOPTS%
48+
echo.
49+
echo.Link check complete; look for any errors in the above output
50+
echo.or in "%BUILDDIR%/linkcheck/output.txt".
3051
goto end
3152

32-
:help
33-
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
3453

3554
:end
3655
popd

‎docs/requirements.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
myst-parser>=0.18
2+
pydata-sphinx-theme>=0.11
3+
sphinx-autobuild
4+
sphinx-copybutton
5+
sphinxcontrib-autoprogram>=0.1.7
6+
sphinxext-opengraph
7+
sphinxext-rediraffe

0 commit comments

Comments
 (0)