\
**Category:** General Usage\
**Tags:** documentation, documenter, literate-programming, github-actions\
**Created:** [August 8, 2021, 5:10pm UTC](https://discourse.julialang.org/t/deploy-literate-non-html-files-with-documenter/66031 "2021-08-08T17:10:11Z")\
**Posts on this page:** 4\
**Page:** 1
**Author:**  [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [August 8, 2021, 5:10pm UTC](https://discourse.julialang.org/t/deploy-literate-non-html-files-with-documenter/66031/1 "2021-08-08T17:10:12Z")
I’m using [Literate.jl](https://github.com/fredrikekre/Literate.jl) to convert example scripts to markdown (`md`) and Jupyter Notebook (`ipynb`) for the documentation. The scripts are in `examples`, and I have a script in [`docs/generate.jl`](https://github.com/goerz/Krotov.jl/blob/master/docs/generate.jl) that gets run as part of [`docs/make.jl`](https://github.com/goerz/Krotov.jl/blob/master/docs/make.jl) to convert the `examples/*.jl` files into `md` and `ipynb` files in the `docs/examples/` folder. I’ve copied this workflow from [Ferrite.jl](https://github.com/Ferrite-FEM/Ferrite.jl). When I execute `docs/make.jl`, I see that (as expected), the output folder `docs/build/examples` contains the `html` file rendered from the `md`, as well as the `ipynb` file for each example.
That is, `docs/build` contains
```julia
.
├── [...]
├── assets
│ └── [...]
├── examples
│ ├── index.html
│ ├── simple_state_to_state.html
│ ├── simple_state_to_state.ipynb
│ ├── state_to_state_rwa.html
│ └──state_to_state_rwa.ipynb
├── index.html
└── [...]
```
The [output from my Github Pipeline](https://github.com/goerz/Krotov.jl/runs/3272290444?check_suite_focus=true) seems to indicate that these files also get properly generated in the CI `build` folder.
However, the `.ipynb` files do not get copied over to the [`gh-pages` branch](https://github.com/goerz/Krotov.jl/tree/gh-pages/dev) during the CI deployment. The `gh-pages` branch contains the following files after deployment:
```julia
.
├── dev
│ ├── api
│ │ └── index.html
│ ├── assets
│ │ └── [...]
│ ├── examples
│ │ ├── index.html
│ │ ├── simple_state_to_state
│ │ │ └── index.html
│ │ └── state_to_state_rwa
│ │ └── index.html
│ ├── index.html
│ └── [...]
└── versions.js
```
I’ve also tried this with the [`prettyurl` option](https://juliadocs.github.io/Documenter.jl/stable/lib/internals/writers/#Documenter.Writers.HTMLWriter.HTML) for `Documenter.jl` set to `false`, which doesn’t help (it just replaces, e.g., `simple_state_to_state/index.html` with `simple_state_to_state.html`)
I haven’t found any documentation for what exactly `Documenter.jl` does during the deployment to `gh-pages`. Clearly, it does not simply copy over the _entire_ `docs/build` folder, as I would have expected. Also, the deployment of the `.ipynb` files [seems to work for `Ferrite.jl`](https://github.com/Ferrite-FEM/Ferrite.jl/tree/gh-pages/dev/examples) as well as [for `Literate.jl` itself](https://github.com/fredrikekre/Literate.jl/tree/gh-pages/dev/generated). I don’t see that I’m doing anything different from those two packages. Does anybody have any experience or ideas on how to get `Documenter.jl` to deploy `.ipynb` files from `docs/build` to `gh-pages`?
---
**Author:**  [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [August 9, 2021, 7:33am UTC](https://discourse.julialang.org/t/deploy-literate-non-html-files-with-documenter/66031/2 "2021-08-09T07:33:29Z")
Could you run `tree` between `makedocs` and `deploydocs` to make sure that `src/` and `build/` are what they should be? E.g. with this snippet:
```julia
cd(() -> run(`tree`), @ __DIR__ )
```
As another breadcrumb, the copying by Documenter happens [in `gitrm_copy`](https://github.com/JuliaDocs/Documenter.jl/blob/e33a4136d0e803b0d5f32bffee45fbb37e516789/src/Documenter.jl#L742-L769). You could add some debug statements there to see what’s happening.
---
**Author:**  [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [August 9, 2021, 7:46pm UTC](https://discourse.julialang.org/t/deploy-literate-non-html-files-with-documenter/66031/3 "2021-08-09T19:46:51Z")
Thanks, that was extremely helpful!
Adding [some of my own `@debug` statements](https://github.com/goerz-forks/Documenter.jl/commit/0d0cb573570fedc0557731ef460390ebf9918678) to `Documenter.jl` shows that it really just copies the `build` folder to the destination directory on `gh-pages`. Running `tree` also [shows that the `ipynb` files do in fact get copied correctly](https://github.com/goerz/Krotov.jl/runs/3283829357?check_suite_focus=true#step:6:311).
The problem is in _commiting_ the changes to the `gh-pages` branch. What is happening is that there is a stray `.gitignore` file in `docs/build/examples` that excludes `ipynb` files. Thus, when `deploydocs` runs [`git add -A .`](https://github.com/JuliaDocs/Documenter.jl/blob/e33a4136d0e803b0d5f32bffee45fbb37e516789/src/Documenter.jl#L629) to deploy to the `gh-pages` branch, the files simply are not added.
The stray `.gitignore` file is originally from `docs/src/examples`, and `makedocs` simply copies it over. That seems like it might be a bug. The reason I have `docs/src/examples/.gitignore` is that I’m generating they `.ipynb` files into that folder before running `makedocs`, but obviously they shouldn’t be committed. I’m not sure I would expect `makedocs` to copy `.gitignore` files to the `build` folder though: I can’t think of a situation where I would want that to happen, but maybe there is one. What do you think? Should I raise an issue for that?
In any case, [manually removing the stray `.gitignore` file](https://github.com/goerz/Krotov.jl/commit/8a9284db751bfdb37202d93225f6cd3a2d0fa08e) between `makedocs` and `deploydocs` completely solves the problem.
Thanks you for your help!
---
**Author:**  [@bgroenks](https://discourse.julialang.org/u/bgroenks)\
**Post date:** [August 29, 2023, 2:04pm UTC](https://discourse.julialang.org/t/deploy-literate-non-html-files-with-documenter/66031/4 "2023-08-29T14:04:32Z")
Thanks @goerz this issue plagued me for ages. Could we maybe add it to the `Ltierate.jl` docs?
Apologies if it’s already there and I just missed it…