Documentation updates -- tentative #180
Conversation
There was a problem hiding this comment.
So far so good. Do we want to make these generated files at CMake time? We could sub in the version (consistently), the branch that the README is on (also consistently), and generate some default status info from commit logs. I think at least the version, and possibly the active branch, would be useful to auto-gen; the status may or may not be a win, but should be easy enough to try.
|
@wrwilliams Do you mean generate all of the READMEs in the API directories at CMake time, or just the status information? |
|
I meant start with template README.md.in files living with our version.h.in and fill in version, branch, status information at CMake time. |
|
Do we still want to keep the generated READMEs in the repository? It might be nice for the users to be able to view the READMEs on github where the markdown is rendered. |
|
Yes, that was in fact the idea: make what the users see automatically generated. If we rely on manual updates for that we're asking for trouble. Of course, we're also asking for trouble on merges unless we can add a merge hook that regenerates the appropriate readmes for the target branch; this seems like it's opening a few cans of worms. We should discuss options for making this problem tractable and automatic, and then talk to @n738cu about how we want to move forward--as a manual thing I'm 90% confident that anything other than a uniform branch status block that stays everywhere will be more trouble than it's worth. |
|
I agree that if we leave branch statuses all over the place then people aren't going to update them and they will just be confusing to our users because they will be out of date. Maybe just a short notes section in each API is sufficient? During the meeting before last Bart was pretty adamant about having branch statuses at the API level but now it looks like it might be more trouble then it's worth. |
|
Regardless of automation, is there anything here that we shouldn't merge over? |
|
No I think everything here is fine now. All of the READMEs now support github syntax so they should now be rendered properly. |
I updated a lot of the old README's to support github markdown. I also added stubs for branch statuses at the API level. I will add descriptions for APIs that don't currently have a description.
Not ready for merge.