Cleanup edocs. Fixes #213 #214
Conversation
- Make rebar3 edoc work - Add some module-level edocs - Add basic doc/overview.edoc - Add edoc to travis
doc/overview.edoc
Outdated
| @@ -0,0 +1,71 @@ | |||
|
|
|||
There was a problem hiding this comment.
Seems kind of redundant when most of this is in the README - and it's an extra thing to keep up to date, potentially.
There was a problem hiding this comment.
Ah, makes sense. The problem is that edoc needs some "overview" page as an index/starting page for edoc. So it's nice to have at least something with a few links to start with.
But I'm agree that it might be better to move all non-basic stuff to the README.
Unfortunately it's not easy to automatically sync readme and edoc.
There was a problem hiding this comment.
I am not really familiar with edocs; could you just link to the README - either locally, or online?
There was a problem hiding this comment.
Well, there is an option - to generate README.md from overview.edoc: https://github.com/uwiger/edown/blob/master/README.md#top-level-readme
But not sure if we should go this way.
There was a problem hiding this comment.
Yep, just hyperlink like http://github.com/epgsql/epgsql/README.md can be added. It's also possible to use any HTML there.
But it's nice to have a few links to start with in overview.edoc
There was a problem hiding this comment.
Ok, I think my proposal is:
We can assume that this generated edoc "target audience" is not end-users of epgsql, but those who need a guide over the source code for some reason (eg, they want to contribute some feature / implement some custom command or datatype). So, we can make this overview.edoc a starting point for them.
So, there will be no "how to use epgsql", but "how to explore epgsql sources" or, in other words, "internal" instructions. So, I will mention 3 APIs as an entry points and describe what is epgsql_sock, epgsql_command, epgsql_codec and epgsql_binary/epgsql_wire and some helper modules.
So, internal docs - edocs, end-user docs - README, with minimal overlap.
What do you think?
There was a problem hiding this comment.
I also plan to rework README a bit. Right now it has a lot of historical introductions (how it is different from original @wg version) on the very top, but I would rather move it to the bottom or remove.
Also want to add some examples of basic session examples (like the one I added to overview.edoc) and a couple of best-practices and HOWTOs, but in a separate PR.
There was a problem hiding this comment.
I think avoiding redundancy is a something to aim for. Otherwise, it's easy for these to get out of sync. I do like the idea of breaking the README up a bit.
|
@davidw I updated the overview.edoc to be more "intarnal" docs and made a couple of other minor changes. |
|
Thanks @davidw ! |
rebar3 edocworkNot sure if generated edoc HTMLs are very usefull, but at least it makes it harder to ignore in-the-code documentation during development.