Skip to content
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.

Sign up for GitHub

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 and documentation updates #1153

Merged
merged 6 commits into from
Mar 10, 2022
Merged

Readthedocs and documentation updates #1153

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
db86a8d
add nox for isolating docs builds
tonyfast Mar 8, 2022
52a55ba
configure sphinx and rtd to install qhub
tonyfast Mar 8, 2022
fba4b54
update outdated rquirements
tonyfast Mar 8, 2022
8c5b19f
revert layout to build from docs folder
tonyfast Mar 8, 2022
62fa235
format python files
tonyfast Mar 8, 2022
58eaf97
update docs instructions
tonyfast Mar 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
# docs
.nox
_build

# setuptools scm
qhub/_version.py

Expand Down
3 changes: 3 additions & 0 deletions .readthedocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,7 @@ version: 2
python:
version: 3.7
install:
- method: pip
path: .
extra_requirements: []
- requirements: docs/requirements.txt
30 changes: 22 additions & 8 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,11 @@

extensions = [
"myst_parser",
"nbsphinx",
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx_copybutton",
"substitute",
]
]

# autoapi.extension
autoapi_type = "python"
Expand All @@ -46,7 +45,7 @@

NAVIGATION_LINKS = {
DEFAULT_LANG: tuple(),
}
}

THEME_COLOR = "4f28a8" # "#7B699F"

Expand All @@ -57,19 +56,34 @@
("posts/*.html", "posts", "post.tmpl"),
("posts/*.ipynb", "posts", "post.tmpl"),
("posts/*.md.ipynb", "posts", "post.tmpl"),
)
)

templates_path = ["_templates"]


html_logo = "source/images/qhub_logo.png"

# exclude build directory and Jupyter backup files:
exclude_patterns = ["_build", "*checkpoint*", "site", "jupyter_execute", "conf.py", "README.md", "ext"]
exclude_patterns = [
".nox",
"_build",
"*checkpoint*",
"site",
"jupyter_execute",
"conf.py",
"README.md",
"ext",
]

latex_documents = [
(master_doc, "qhub.tex", "Infrastructure as Code", "QHub", "manual",)
]
(
master_doc,
"qhub.tex",
"Infrastructure as Code",
"QHub",
"manual",
)
]

jupyter_execute_notebooks = "off"

Expand All @@ -78,7 +92,7 @@
# Import qhub version number
here = os.path.abspath(os.path.dirname(__file__))
__version__ = None
exec(open(os.path.join(here,'../qhub/version.py')).read())
exec(open(os.path.join(here, "../qhub/version.py")).read())

qhub_version_string = __version__

Expand Down
21 changes: 1 addition & 20 deletions docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1 @@
black
click
importnb
ipykernel
IPython
isort
myst-parser
nbconvert
nbformat
nbsphinx
pre-commit
pydata-sphinx-theme
pytest
sphinx_rtd_theme
sphinx-autoapi
sphinx-copybutton
sphinx-copybutton
sphinx-material
sphinxcontrib-bibtex
stringcase
jupyter-book
Copy link
Contributor

@viniciusdc viniciusdc Mar 8, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @tonyfast, is this enough for building the docs (I know that it worked based on the succeeded build you provided)? I noticed that it has all the sphinx-related dependencies that we might need, but is there anything else we need to add as well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

jupyter-book has a ton of dependencies. most of them are to incorporate markdown/notebooks as sphinx documentation source. all those prior deps are taken care of by jupyter-book.

8 changes: 8 additions & 0 deletions noxfile.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
from nox import session


@session(reuse_venv=True)
def docs(session):
session.install("-e.")
session.install("-rdocs/requirements.txt")
session.run("sphinx-build", "docs", "_build/html")
Comment on lines +1 to +8
Copy link
Contributor

@viniciusdc viniciusdc Mar 8, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was reading the nox description and it seems very interesting, but I didn't quite understand how it is been used here exactly...

Copy link
Contributor Author

@tonyfast tonyfast Mar 9, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry i missed that description. i added instructions to docs/README.md for building the docs. you'll need nox, pip install nox. run the nox docs session as:

 nox -s docs

nox is a tool to ensure that sphinx builds in its own virtual environment, and doesn't effect the developer's primary environments. its specifically good for something like jupyter-book that has a lot of dependencies that are better isolated from other environments. also, it provides a convenient cli that can work locally/ci.