Follow symlinks when walking the docs directory

[fingolfin]

This way external directories with a bunch of markdown files can be easily included.

This is not a perfect solution but it works surprisingly well in practice. We've been using it for some time in Oscar.jl via some hacky monkey-patching...

[fingolfin]

@fredrikekre @mortenpi thoughts on this? I could refine it but of course if you outright say "no way", I'll rather not... :-)

[mortenpi]

Sorry for the delay. This seems fine to me to be honest. I also don't expect this to be breaking in practice -- since they don't work, I wouldn't expect any real docs/src directories to actually contain symlinks to directories.

@fredrikekre @odow @goerz, can you foresee any potential issues with this?

If no-one sees any issues with this, then I think it could just use a small test case and a CHANGELOG note.

[fingolfin]

@mortenpi thank you. My colleague @aaruni96 will probably take over and work on a changelog and testcase.

For the testcase, we are trying to understand the test setup. From a few minutes looking, my naive idea would be to go into https://github.com/JuliaDocs/Documenter.jl/tree/master/test/examples/src and add a new file symlink.md which is a symlink to one of the other .md files (or a simple new file, or maybe to an .md file in an outside directory). And then perhaps after the docs are built, check if there is a symlink.html and whether its content is identical (or close enough) the the output produced for whatever file the symlink pointed at.

Does that sound plausible? Or any better suggestions? Anything we should watch out for?