draft windows instructions #642
Conversation
docs/advanced/advanced.md
Outdated
|
|
||
| Jupyer-book current reads and writes files on windows in the native windows encoding, which causes encoding errors for some characters in UTF-8 encoded notebooks. | ||
|
|
||
| **Work-around:** Beginning with [Python 3.7](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUTF8) cmd.exe or powershell enviroments that set PYTHONUTF8=1 override the native locale encoding and use UTF8 for all input/output. To make it easier to use this option, we have created a conda package [runjb](https://anaconda.org/eoas_ubc/runjb) which [does this automatically for powershell](https://github.com/eoas-ubc/eoas_tlef/blob/master/converted_docs/wintools/binwin/runjb.ps1) |
There was a problem hiding this comment.
Can we put the "to make it easier to use this option" section into a {tip} block? Also, we should clairfy what "we" here means eoas_ubc so it doesn't confuse people 👍
docs/advanced/advanced.md
Outdated
|
|
||
| 1. Character encoding | ||
|
|
||
| Jupyer-book current reads and writes files on windows in the native windows encoding, which causes encoding errors for some characters in UTF-8 encoded notebooks. |
There was a problem hiding this comment.
| Jupyer-book current reads and writes files on windows in the native windows encoding, which causes encoding errors for some characters in UTF-8 encoded notebooks. | |
| Jupyer-book currently reads and writes files on windows in the native windows encoding, | |
| which causes encoding errors for some characters in UTF-8 encoded notebooks. |
docs/advanced/advanced.md
Outdated
|
|
||
| Jupyer-book current reads and writes files on windows in the native windows encoding, which causes encoding errors for some characters in UTF-8 encoded notebooks. | ||
|
|
||
| **Work-around:** Beginning with [Python 3.7](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUTF8) cmd.exe or powershell enviroments that set PYTHONUTF8=1 override the native locale encoding and use UTF8 for all input/output. To make it easier to use this option, we have created a conda package [runjb](https://anaconda.org/eoas_ubc/runjb) which [does this automatically for powershell](https://github.com/eoas-ubc/eoas_tlef/blob/master/converted_docs/wintools/binwin/runjb.ps1) |
There was a problem hiding this comment.
Could you try capping line lengths around 80 characters and splitting long lines across multiple ones?
docs/advanced/advanced.md
Outdated
| @@ -192,6 +192,49 @@ The contents of `extra_navbar` will be inserted into your page's HTML after | |||
| all other html content. | |||
|
|
|||
|
|
|||
| ## Working on Windows | |||
|
|
|||
| As of May 27, 2020, there are three open issues that require Windows-specific workarounds: | |||
There was a problem hiding this comment.
I think we should add something to the effect of "note that behavior on Windows may still be unstable, and these workarounds are community tips but are not guaranteed to solve your problem"
docs/advanced/advanced.md
Outdated
|
|
||
| 3. Nested tables of contents | ||
|
|
||
| Currently, `_toc.yml` files that reference marrkdown files |
There was a problem hiding this comment.
| Currently, `_toc.yml` files that reference marrkdown files | |
| Currently, `_toc.yml` files that reference markdown files |
docs/advanced/advanced.md
Outdated
|
|
||
| 3. Nested tables of contents | ||
|
|
||
| Currently, `_toc.yml` files that reference marrkdown files |
There was a problem hiding this comment.
do we know why this is?
| After the build, view the html with: | ||
|
|
||
| `start docs\_build\html\index.html` | ||
|
|
There was a problem hiding this comment.
can you remove the extra whitespace so there are only 2 spaces max?
There was a problem hiding this comment.
think I've addressed comments -- re nested _toc.yml, curently getting an MRE so I can run side by side on window and wsl2 -- has to be something fairly simple.
|
hey @phaustin - any chance you could clean up this one and we can get it merged? I think it'd be helpful for many folks! |
|
yes, I'll go ahead and do that tonight -- thought I'd have the encoding problem sorted yesterday, but ran out of time. |
|
@phaustin I want to add a note directive with a link to your documentation here to inform windows users. I hope it will minimize the number of submitted issues related to this problem. What I have in mind is something like this: with the assumption that "(working-on-windows)=" is located right above this header "## Working on Windows" I would be happy to add this once you're done or if it's better for you, I can work on it prior to you making these changes. Lmk how you'd like to proceed. |
|
hmmm, seems like we might have some re-base weirdness? |
|
@choldgraf @najuzilu -- think this is ready: https://deploy-preview-642--jupyter-book.netlify.app/advanced/advanced.html#working-on-windows |
|
Looks great! Thanks very much @phaustin for the contribution, and for helping to find, document, and iron-out these bugs! 🎉 |
I'm still getting a build failure with a nested _toc.yml ala #573 so I've forked quantecon-mini-example and checked in a branch with a single level toc that builds successfully.