Allow README.md to be used as the index page

[SEJeff]

If index.md exists, it will be
preferenced over README.md, to match the featureset of readthedocs as the index page.

Fixes #608

I'm not sure what you require as far as documentation goes, but first wanted to make sure this, or something like it is reasonable. I used the maxsplit argument to str.split(), so there shouldn't be any unexpected surprises.

[SEJeff]

The path.replace could likely be better, but again, I figured it was easier to get a yay or nay on the approach and go from there before this gets merged.

[d0ugal]

That seems reasonable to me.

[d0ugal]

This looks reasonable, I am not 100% sure what will happen if you have both an index and a README file tho' - presumably one will write over the other and the page will be lost?

[d0ugal]

Okay, so I have tested this with the MkDocs documentation.

• If I just rename the index.md it works pretty great
• We probably need to update this too. I forget exactly where it is used, but it will show Home in the nav rather than README.
• If I duplicate the index.md to README.md we run into some issues.
  • We have two navigation items that point to the same location.
  • The homepage shows the README.md and the index.md isn't accessible.

I think having both is going to be a relatively uncommon use-case, but probably still a valid one.

FWIW, this is what I see. Regardless of if I click on Home or README the README nav is highlighted and the README page is shown (I modified the title so I knew).

[d0ugal]

I am also trying to figure out what documentation changes are required. It seems we never explicitly state that an index.md is required. So I would suggest just adding a brief mention in the docs here to say something like...

MkDocs will use the index.md file for your home page, if that isn't found it will also try README.md

[d0ugal]

I am trying to think how we can better approach this issue. The problem is that where we set the output path, we don't have any context of what other pages exist.

[SEJeff]

I'm going to close this for now. This clearly will need a lot more work.

[d0ugal]

@SEJeff Thanks for your effort, it might be something like this would be easier with @tomchristie's factoring. I don't think it is specifically a goal of his, but he might have some ideas.

[lovelydinosaur]

Actually the 'refactor' branch does already handle this. I'm not too concerned about clashing 'index.md' and 'README.md' files, simply warning if this occurs would be sufficient, and also be easy to do.

[d0ugal]

Awesome. My main motivation for this is that it is a common GitHub pattern, ReadTheDocs hacks support in for people as it is.