Paths are relative to you, not the config file #543
Comments
I think that is a reasonable compromise. Not sure when I would want to point to a config file in a different location anyway. If I had multiple config files for one project, they would most likley be side-by-side in the root of the project anyway:
Or I suppose the various config files could be in a subdir:
Either way, I would be calling the When automating doc builds (in a tox config or from a make file) one may need to cd into the project root before building, but that is nothing unusual (and good practice anyway). Maybe the commands could accept a |
Okay, fair point. I mostly wanted to raise this and have some sort of record of it. I think I agree, so, closing this for now :) |
The case I care about (from issue #676) is when performing out-of-tree builds. I treat my build system as a toolbox of commands, and being able to run While MkDocs itself is unlikely to benefit from from out-of-tree builds, it means that for my projects, I'm either forced to run mkdocs directly[1] or handle [1] Which is more typing, since I prefer to use |
Yeah, so it is interesting that you hit this when doing automation like I did. I think we should try and fix this, I can't really see how the paths being relative to the user makes sense. Personally, I found it really easy to work around, I don't think it is that hard, but the fact that the config essentially changes as you move around the file-system is weird. I think for this to work well, we would need to join each config option with the path to the mkdocs yaml when we do all the config processing in https://github.com/mkdocs/mkdocs/blob/master/mkdocs/config/config_options.py |
Just agreeing that I think this is a valid issue |
So, rather than:
You'd prefer to use the following line in your automation scripts:
Where the paths in the config file are presumably relative to the config file. Sorry, but it is not clear to me how this is better. For that matter, it is not clear how the current way is better either (even if it is a few less characters of typing). What is clear is that it is different, which means that many existing users will need to change there config files if a change is made. And for what benefit? |
I don't see why using |
A very simple solution would be for MkDocs to to change it's cwd to the config file.
This is a nasty nasty hack tho' |
Def don't do that. ^ :) |
@waylan: Well, given the build system I use, it's more like:
vs
Even the above isn't really perfect, since it'd break if the user was running the build system under Python 2.x. It's also something that took me a while to figure out, since I wasn't even thinking about the current-directory issue. (Granted, some of this is the fault of the build system making it somewhat difficult to I agree that it's not the world's biggest issue, but it's a rough corner that makes things less convenient, when the only real benefit I can see is that it keeps the code somewhat simpler. I could probably patch the build system to do this in a slightly cleaner way if this bug were wontfixed, but I still think it would be a nice fix for MkDocs. Maybe it's more of a philosophical argument, but I've never liked it when programs unnecessarily depend on the current directory. It usually just ends up confusing me when I run into an error (I rarely think about what the cwd will be when I'm writing an automation script). |
I've seen this done before, and I guess I've been guilty of doing it myself. I'm not sure I would call it a hack if nothing else cares about the actual current working directory though. I really see no problem with controlling your current working directory if you have a good reason to. It would be completely transparent to the user, and it seems like Mkdocs doesn't care about the actual cwd. You could always restore the actual cwd when Mkdocs is done. If you aren't changing the cwd, you are just going to have to pass around Mkdocs calculated working directory, and then make everything relative to that. Seems like a lot more work to me when Now if you needed to track the actual cwd and Mkdoc's cwd directory for some reason, then yeah, this is not an ideal solution and it should probably be handled differently by passing around your paths. Meh, that's just my thoughts. |
Not sure if that would even be necessary, since a child process can't change its parent's cwd (which is why |
If Mkdocs was a library, then it would, but Mkdocs isn't really a lib, so your probably right. |
That would not help at all. For people who have a setup in which the cwd is not the directory in which the config file resides, this would break their setup the same way as making all paths relative to the config file's path. So, yeah, it would be a hack. Don't do that. |
I think that's the point. Since MkDocs isn't 1.0 yet, you can't really expect the config file's semantics to remain 100% set in stone. |
Ahh, then yeah, if that is a concern, then it is a problem. I'm not sure of all the ways it is being used and ultimately what is planned for final usage in 1.0.
True, but it depends on Mkdoc's goals, which I am unaware of in regards to this. |
While not a library, we tread into that territory once we have a plugin API. So, yeah, I don't think we want to change the cwd. |
I don't think it's actually that hard to detect if the semantics change would break your build, assuming we care enough to detect it. Some observations:
Therefore, you should be able to get pretty darn close to automatically detecting all cases where this would change. Just check both the cwd and the
Eventually, say at 1.0, you can drop all of this logic and always use the |
The slight irony of using ReadTheDocs as an example is that users have no control over the CWD in that example. So the documentation should build consistently on RTD's and however you build it elsewhere. This wont happen if the user requires something specific like calling from the parent. I do believe that RTD is a large proportion of ours users, many people come to us as they want to use RTD but don't want to learn Sphinx/reStructuredText.
I can see a couple of options.
This sounds like how lots of users do it on ReadTheDocs, they don't call from the parent tho' - often the root of the git repo is the docs_dir. So the config is within the docs_dir, that caused an annoying bug :)
I believe that one of the biggest goals of MkDocs is to have sensible defaults and be as unsurprising as possible. If we don't change these things early on, then they will only get harder to change later. |
All things being equal, I'd vote for detecting as much non-standardness as possible, complaining loudly if any is found, and enforcing as minimal-as-possible set of different-ways-to-do-a-thing headed into 1.0.
Hear hear! Now is the moment. |
Alright then. Sounds like the consensus is that the breaking change is worth it. Please, just don't use the |
I won't. If that is required to make it happen I might be swayed against the change. |
Alternative: remove |
You may have a point. But I suspect you will get more complaints from people by making that change than anything else. And it will be a never-ending feature request. |
The downside of this is that it's more complex for my case: I want to build documentation from my build dir, and then put the HTML in a subdirectory of the build dir. This makes cleaning a build trivial: |
A strong +1 for making the paths relative to config - or at least add whatever extra option to enable that. I sure as hell don't want to cd back and forth. Cding to the docs dir prior to mkdocs build may sound reasonable when you compare just the command lines to run mkdocs, but that is an insufficient comparison. I would think anyone spending a lot of time in unix shells doing varying tasks in various apps will understand that. Having to juggle between dirs is a pain, even with push & popd. I am using mkdocs to generate API documentation for a Python package. In my case, the mkdocs sources are using Jinja templating and are kept within the package. So I run a sort of preprocessor (Jinja etc) to generate "static" mkdocs sources outside the package tree. Including mkdocs.yml. To work around the current situation, I have to hardcode paths in the preprocessor step to be able to properly run the final mkdocs build step in the end. Which feels insane. At some point I will just use mkdocs as a library, so I hope I will be able to sidestep the issue, but not there yet... |
Ironically (as I've been the voice against this change), I just came up against a need for this feature. If you are deploying to user/organization GitHub pages, you need this. User/org pages do not commit to the cd project-repo
mkdocs build
cd ../pages-repo
ghp-import -b master -p ../project-repo/site If paths in the config were relative to the config file rather than the CWD, then this would work:
But as long as paths are relative to the CWD, that will never work. And as you need to run the command from the repo you are committing to, I think this is the use-case that pulls me over. We now have a reason to make the change which overcomes my previous objections. |
Is this available yet? I am on version 0.17.4 and it seems like paths are still relative to my cwd. My use case:
This gives me However from this discussion and the merged pull request it seems that this should work. |
This will be available in the next major release: 1.0. |
I was confused because the docs at https://www.mkdocs.org/user-guide/configuration/#docs_dir say otherwise:
If this is not available yet, I think the documentation should either explicitly say that as such, or only current behavior should be mentioned. |
You can do
mkdocs build --config-file=path/to/mkdocs.yml
but any configuration values in that file are relative to your current working directory.This seems wrong to me, but it's only something I've ran into when trying to automate MkDocs builds (for integration testing). I'm not sure if we want to change this, or what people really expect. The common use case is that you are in the same directory as the config file anyway, so that doen't matter.
Something like this should be changed or at least decided for a 1.0 release.
Thoughts?
The text was updated successfully, but these errors were encountered: