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

Add a FAQ section in the documentation #258

Closed
mwouts opened this issue Jun 20, 2019 · 1 comment
Closed

Add a FAQ section in the documentation #258

mwouts opened this issue Jun 20, 2019 · 1 comment
Milestone

Comments

@mwouts
Copy link
Owner

mwouts commented Jun 20, 2019

It would be nice to have a FAQ in the documentation, plus a link to that in the README. The FAQ should be easy to follow, even by a person that had never heard of Jupytext.

Among the questions there I'd like to see

  • What changes in Jupyter when I install Jupytext? A1: you gain the possibility to pair notebooks, but unless you pair a notebook, they continue to work in exactly the same way. A2: Scripts and Markdown files get a notebook icon. In Jupyter lab they gain an 'open with notebook' item in the contextual menu in JupyterLab. In Jupyter Notebook they open as notebooks by default
  • Can I use Jupytext with JupyterHub? A: Yes. Install it globally or locally (pip install jupytext --user). If it's installed globally and that a specific user doesn't want it, he can deactivate the server extension (and the other extensions).
  • Can I user Jupytext with cloud notebook editors? A: Not in their interface (yet?). But you can use the CLI Document how to use Jupytext with Hub/Colab/Saturn/Azure/nteract etc #256
  • Can I use Jupytext on Binder? A: Yes: jupytext in requirements + install lab extension
  • How do pair notebooks work? A: inputs + outputs in ipynb, input and metadata only in the text files, inputs in the text file have a precedence over those in the ipynb file
  • Some metadata is missing in the paired file! A: tell about filters. A:filtered metadata is preserved in the ipynb file
  • I get a message 'the notebook has changed on disk'? A: Be faster than autosave... or turn it off. A: Use an editor that can show the diff memory vs disk.
  • I love Jupyter widgets, does Jupytext support them? A: Yes. In the paired files, Jupytext saves every part of the notebook that was writen by the user (cell inputs and metadata).
  • Is Jupytext safe to use? A: We try our best! Round trip is well tested: covered with 1000+ tests. A: Safer than without as you now see the diffs before commit A: Editing the same document in two editors simultaneously must be done with attention, please be careful. Still it should be hard to make a mistake (we check timestamps, etc)
@mwouts mwouts changed the title Add a _frequently asked questions_ to the documentation Add a FAQ section in the documentation Jun 20, 2019
@mwouts
Copy link
Owner Author

mwouts commented Jun 30, 2019

The FAQ could also include a short mention of #267 #268 #263 #251

@mwouts mwouts added this to the 1.2.0 milestone Jun 30, 2019
mwouts added a commit that referenced this issue Jun 30, 2019
@mwouts mwouts closed this as completed in 9d7ae13 Jul 2, 2019
mwouts added a commit that referenced this issue Jul 6, 2019
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

No branches or pull requests

1 participant