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.

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

automate notebook doc-making #28

Merged
merged 1 commit into from
Jun 14, 2023
Merged

automate notebook doc-making #28

merged 1 commit into from
Jun 14, 2023

Conversation

eacharles
Copy link
Collaborator

No description provided.

@OliviaLynn
Copy link
Member

Looks good! The one catch is that we'll need to add something in the documentation about installing pandoc if users wish to build the notebooks locally with sphinx (as pandoc is a haskell library, so we can't bundle it into pip requirements)

Without pandoc in my rail conda environment, running make html from the docs/ directory of this PR results in an interrupted run and:

Notebook error:
PandocMissing in examples/core_examples/FileIO_DataStore.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html

Running conda install pandoc allows make html to run as expected.
Proposed solutions include:

  • explaining this in the documentation, in a section relevant to devs trying to build notebooks (or documentation in general) locally
  • we could also include a comment in our Makefile, in the hopes that anyone encountering trouble with make commands will read that
  • we could include pandoc in our other conda packages in the standard rail install instructions, but I hesitate to add that kind of overhead for such a relatively niche use case

(This should not be an issue on ReadTheDocs, as pandoc should be automatically included. If I recall, there is a toggle in Advanced Settings where you can remove this, but unless we run into issues we can assume we don't have that set.)

@eacharles eacharles merged commit 2d2be07 into main Jun 14, 2023
@eacharles eacharles deleted the issue/15/sphinx-build branch June 14, 2023 23:22
@eacharles eacharles mentioned this pull request Jun 14, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants