Skip to content

Feature: add support for .py files in plaintext formats #1498

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

Open
lukastk opened this issue Feb 22, 2025 · 2 comments · May be fixed by #1499
Open

Feature: add support for .py files in plaintext formats #1498

lukastk opened this issue Feb 22, 2025 · 2 comments · May be fixed by #1499

Comments

@lukastk
Copy link
Contributor

lukastk commented Feb 22, 2025

Add support for exporting the following plaintext formats as if they were regular .ipynb files:

  • percent
  • light
  • sphinx
  • myst
  • pandoc

See this for details on the above plain-text notebook formats. This feature is inspired by this article, where the author also requested it.

(Note: This is a reissue of a previous poorly attempted pull request)

@lukastk lukastk linked a pull request Feb 22, 2025 that will close this issue
@hamelsmu
Copy link
Contributor

Thanks for sharing the blog post with the section on proposals for nbdev. I enjoyed reading that. However saving outputs is important for rendering docs, so I don't think saving to plain text would work? Please let me know if I'm wrong

Also this increases the surface area of maintenance which I am not sure we want to do.

cc: @jph00

@jlopezpena
Copy link

jlopezpena commented Mar 7, 2025

In the jupytext approach, the notebooks are run (and their output stored) when generating the documentation, but there is no need to keep the notebook output under version control. The one thing one loses is the diffs in PRs that would show if an output where to change. The way around that is to have the documentation folder itself under source control.

My personal opinion is that keeping the myst-nb files (or any other plain text instead of notebooks) as source of truth makes code reviews much easier. If you don't want to carry the extra dependencies with jupytext and myst-markdown, perhaps this could be an optional feature? eg something one would install with pip install nbdev[md] or similar.

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 a pull request may close this issue.

3 participants