New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Generate README.md #12
Comments
So generate a |
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.
? |
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? |
At the moment it's ok. If you generate the README and have
in the README, then it should (recursively) include all of the previous README. Right? |
So
then run
copy/link that to |
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. ... |
Agreed, I guess that if someone wants to generate the README they could add a
to their |
Perhaps just having a description of how to do that in a "tips and tricks" section of the manual would be enough? |
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. |
That might be a better approach @hayd. So when |
Has there been any progress on this issue? I looked up some information on |
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 |
One issue here is that it would need to be committed to master rather than in gh-pages. |
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:
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. |
One reason that this is useful is that when you do 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).
👍 Whether that's people misusing README (instead of fully committing to the docs), might be debatable... 😀 |
I'm doing a triage of open documenter issues and closing issues that are stale. If I've made a mistake, please re-open Closing because Documenter is not in the business of modifying or creating people's READMEs. And people can add docstrings to their modules. There has also been no action on this since 2016 so it doesn't seem to be a priority. |
Most likely this should also go into build as
index.md
.The text was updated successfully, but these errors were encountered: