Add option to change root path during build.

[kescobo]

Assuming a standard project layout,

MyPackage
    ├── src
    │   ├── MyPackage.jl
    │   └── functions.jl
    ├── docs
    │   ├── makedocs.jl
    │   └── src
    │       ├── 01-foo.md
    │       ├── 02-bar.md
    │       └── index.md
    ├── test
    │   └── runtests.jl
    ├── Manifest.toml
    ├── Project.toml
    └── README.md

I'd like to be able to set an option such that makedocs() will execute code in MyPackage/docs/src/01-foo.md as if the current working directory is MyPackage/.

I tried

makedocs(
    ...
    root=joinpath(dirname(pathof(MyPackage)), ".."),
    source="docs/src",
    build="build")

thinking that the root option was what I wanted, but pwd() in a code block returns MyProject/build/. I also tried setting the build="."... oops #1012

The reason for this desire is that I'm using the markdown files as interactive data analysis notebooks with Juno, and Juno sets the current working directory as the package root. I'd like to use Documenter to render html versions of the analysis notebooks, but would prefer not to go through and change all of the paths to the input data and output folders.

Is this possible, even with some sort of hacky solution? I'm happy to work on a PR if I this would be useful for others, and if I can get a bit of direction about where to start.

[mortenpi]

Hmm. How are you building the notebooks in Juno such that you're getting a different working directory? Are you just doing include("docs/makedocs.jl") or something else?

Would an at-setup block in each .md file where you cd to the correct directory work?

[kescobo]

How are you building the notebooks in Juno such that you're getting a different working directory? Are you just doing include("docs/makedocs.jl") or something else?

Yes, exactly that. Happy to have a different procedure though - this is going to be a manual, not an automated process.

Would an at-setup block in each .md file where you cd to the correct directory work?

Yeah, I thought about this. It's a little messy, but if it works... I was thinking of something simple like

```@example 1
cd(joinpath(dirname(pathof(MyPackage)), "..")) # hide
```

In the first code block of each notebook. Is there a better option?

[kescobo]

Actually, that doesn't seem to work - during the build, MyPackage is not defined. Do I have to add it to a doc Project.toml or something?

[fredrikekre]

Yes, but most importantly you need to using MyPackage before using it.

[kescobo]

In fact - that doesn't actually work. MyPackage is not defined during the build. I tried adding it to the [deps] in a Project.toml file inside docs/, but that did not help (guessing that only matters for travis??).

But I also tried something a bit more cloodgy and it didn't work either. I can't seem to get out of the build directory no mater what:

```@example 1
cd("../../../")# hide
pwd()
```

```@example 1
cd("..")
pwd()
```

[kescobo]

@fredrikekre Sorry - missed your comment because my other comment is staying at the bottom of the thread for some reason...

[kescobo]

@fredrikekre Your suggestion allows the code to evaluate, but still doesn't let me out of the build directory:

```@example
using ECHOAnalysis # hide
cd(joinpath(dirname(pathof(ECHOAnalysis)), "..")) # hide
pwd()
```

[fredrikekre]

The problem is that we cd to the build page for every evaluation:

Documenter.jl/src/Expanders.jl

Line 543 in 38dc754

cd(dirname(page.build)) do

You can probably workaround it with

cd(...) do
    # stuff
end

[kescobo]

That would have to wrap every code block right? Might be too heavy-handed for me. Would there be any interest in a PR that allows this to be user specified? Eg something like

makdocs(
    ...
    eval_dir=:build # or user-specified path
)

?

[mortenpi]

Yes, I think we could have an option like that. Bikeshed: maybe call it working_directory or something along those lines?

One thing to think about though: currently, if I am not mistaken, we cd into a subdirectory of build/ (e.g. docs/src/foo/bar.md cds into docs/build/foo/bar/). Would have to think how to handle that. I guess though, if you are overriding the working directory, you probably always want to be there.

Another idea would be to have a per-file at-meta block option for this?

[kescobo]

Bikeshed: maybe call it working_directory or something along those lines?

Agree - that's much clearer :-)

Another idea would be to have a per-file at-meta block option for this?

I like this idea. Would this be instead of or in addition to an argument in makedocs()? Presumably, if both, the meta block would override what's in makedocs() (or maybe have the path defined in a metablock be relative to whatever is specified in working_directory)?

I can dig around in the source code to get started on a PR, but is there a good place to start to understand the processing pipeline? I read through the contributing page, and my plan was to start here at the source for Document and start looking around, but if you have any suggestions to make me more efficient, I'd be happy to hear them,.

[mortenpi]

#1025