Documenter.jl: Generate README.md

[hayd]

Most likely this should also go into build as index.md.

[MichaelHatherly]

So generate a docs/build/index.md and also copy it to README.md? We could also just link README.md to index.md with a soft link, if that actually works in github?

[hayd]

Note: At the moment a module without a docstring fallsback to its README. I think this is going to be circular if generating a README with the top-level module.

1. README generation should be first.
2. Having the package module docstring IN a README (if it is falling back) at this stage should be disallowed... :s

?

[MichaelHatherly]

Yeah, could be a problem though I've been trying to get it to break things with little success. What steps are needed to cause trouble?

[hayd]

At the moment it's ok. If you generate the README and have

{doc}
Lapidary

in the README, then it should (recursively) include all of the previous README. Right?

[MichaelHatherly]

So /doc/src/README.md with

{docs}
Lapidary

then run julia doc/build.jl and get /doc/build/README.md as

[contents of /README.md...]

copy/link that to /README.md and repeat? Yeah, probably should raise an error in that case, though I think it would need multiple runs of build.jl to happen, can't just recursively expand in a single run, hopefully.

[hayd]

Bump! IMO it's nice to have a somewhat verbose README since (at least by default) this is shown when you do ?Module. However, this seems to go against the spirit of Documenter's main/advertised build method, which is to commit only to gh-pages. ...

[MichaelHatherly]

it's nice to have a somewhat verbose README

Agreed, I guess that if someone wants to generate the README they could add a

cp("build/README.md", "..")

to their make.jl after the makedocs call. That does mean you have to manually commit generated content to the repo though. Also, relative links wouldn't work probably, would need to write any of those manually.

[MichaelHatherly]

Perhaps just having a description of how to do that in a "tips and tricks" section of the manual would be enough?

[hayd]

Another options is to have the readme static (no expanding), but map to index.md (ONLY if index.md is not present) e.g. cp to src/index.md, makedocs, then rm src/index.md.

Edit: In that way it can at least be doc tested.

[MichaelHatherly]

That might be a better approach @hayd. So when docs/index.md does not exist then see if README.md is available and use it's content in place of index.md (we probably don't even to cp and rm it I think)?

[pwl]

Has there been any progress on this issue? I looked up some information on README.md generation and there is nothing on this topic there. What is the canonical way to generate a readme file?

[MichaelHatherly]

No, not at the moment. I've not found any need myself for generating a readme, and prefer the new HTML rendering (which can't really be used in a GitHub readme page), so this hasn't really been high on anyone's priority list.

There's no canonical way to do it, but you could probably get by with a docs/src/README.md file which, after generating the corresponding docs/build/README.md, is just cped into the toplevel of the package repo before committing the changes.

[hayd]

One issue here is that it would need to be committed to master rather than in gh-pages.

[mortenpi]

Just wanted to put my two cents in: I don't think Documenter should commit to the code branches -- seems a bit fragile and would clutter the history. So I would propose two alternative approaches:

1. It could be done using a script that updates the README.md, but the contributor has to call it manually when there have been changes that would be visible in the README (similar to Julia's doc/NEWS-update.jl). We would probably need a docs/README.md file in this case that would be the source and could contain Documenter's @-blocks etc.

Since the README contents should be deterministic, we could also test that the README is up to date, by generating a temporary copy on Travis and comparing the files. Also, I think this should work even if the main docs are HTML -- we could generate a Markdown README in addition to that (might need some work on Documenter's internals though).

1. If the primary issue is just the duplication of information in the README and the docs, then perhaps we could have a mechanism to include the contents of the README.md into a page in the docs. The README would in this case still be static though.

In any case, I think it would be nice if we could document some specific use cases, so that we could make better decisions on how it should be implemented exactly. I also don't foresee myself using this at the moment, but it sounds like it could be a nice feature in principle.

[hayd]

One reason that this is useful is that when you do ?Package at the julia promt, the default (if there's no docstring for the module) is to shown the (rendered) README.md. That's not very compelling.

If Documenter complains if you don't define a docstring for the package I think that would solve that one.

---

IME another is that sometimes people like to have a couple of short/key examples in their README.md, to give potential users an idea of the package _immediately_, and it's nice to be able to generate these (for which I think a manually-triggered script would be fine, they shouldn't change often).

we could also test that the README is up to date, by generating a temporary copy on Travis and comparing the files.

👍

Whether that's people misusing README (instead of fully committing to the docs), might be debatable... 😀