Documentation

[hbcarlos]

Done

• Adds Sphinx
• Sphinx Autodoc for Python API docstring
• TypeDoc for JavaScript API docstring
• Configure Read The Docs

TODO:

• Write an overview
• Document schemas
• Explain how to create a custom model
• Write docstring for the python package
• Check docstring for the javascript package

Screencast

Screencast.from.11-24-2022.10.45.24.AM.webm

[davidbrochart]

Wow, that's great, thanks a lot Carlos!

[hbcarlos]

@davidbrochart, Do you know if I can ignore the docs folder for the link_check workflow?

[davidbrochart]

Maybe do the same as jupyter-server/jupyter_server@05913dd ?

[davidbrochart]

Maybe do the same as jupyter-server/jupyter_server@05913dd ?

Ah, it's already there.

[hbcarlos]

Thanks, @davidbrochart!

Yes, it is already there. Anyway, I'm reorganizing the index to remove the failing links, and I can maybe build the docs before checking the links for the remaining link.

[davidbrochart]

But link_check is actually failing for a good reason, right? For instance, there is no ./api/index.html yet.

[hbcarlos]

Yes, because that link points to the TypeDoc documentation for the javascript package that is generated when building the docs. That link will always fail, we need to ignore it.

[davidbrochart]

Ah I see, I don't know if it's possible to exclude a single link.
Otherwise, why not have an empty file, that will be overwritten when building documentation?

[hbcarlos]

Yeah, that is a solution. I can generate that file when building the documentation.

[hbcarlos]

@davidbrochart. Much easier, I added a placeholder file, so the link doesn't fail.

[davidbrochart]

I can see that when clicking on JavaScript API, it goes to a different layout, without the top banner. Is it expected?

[hbcarlos]

I can see that when clicking on JavaScript API, it goes to a different layout, without the top banner. Is it expected?

Yes, it is the same JupyterLab does.

It is because I'm using TypeDoc to automatically generate the documentation of the JavaScript package from the docstring. That generates a completely different webpage that I copy to the build folder of the Sphinx documentation, see:

jupyter_ydoc/javascript/package.json

Line 28 in 4c958a9

"docs": "typedoc --out ./docs src",

and:

jupyter_ydoc/docs/source/conf.py

Lines 82 to 101 in 4c958a9

	# Build JavaScript Docs
	js = HERE.parent.parent / "javascript"
	js_docs = js / "docs"
	dest_dir = Path(app.outdir) / "api"
	if js_docs.exists():
	# avoid rebuilding docs because it takes forever
	# `make clean` to force a rebuild
	print(f"already have {js_docs!s}")
	else:
	print("Building jupyterlab API docs")
	check_call(["npm", "install"], cwd=str(js))
	check_call(["yarn", "run", "build"], cwd=str(js))
	check_call(["yarn", "run", "docs"], cwd=str(js))
	# Copy JavaScript Docs
	print(f"Copying {js_docs!s} -> {dest_dir!s}")
	if dest_dir.exists():
	shutil.rmtree(str(dest_dir))
	shutil.copytree(str(js_docs), str(dest_dir))

There is an extension for Sphinx, sphinx-js, that does everything inside sphinx, but it doesn't work yet with the jinja2>=3. See: mozilla/sphinx-js#191
And the latest Sphinx uses jinja2>=3. In addition, jupyter-server, jupyterlab, and some other packages that we need to install in the same env all use jinja2>=3, soo it makes everything more complicated for development.

[hbcarlos]

I would like to merge and do the remaining tasks in follow-up PRs. This way, we can set up the Read The Docs project and check that everything works.

[davidbrochart]

Thanks!