Update documentation #774

Open
karussell opened this Issue Aug 22, 2016 · 24 comments

Projects

None yet

5 participants

@karussell
Member
karussell commented Aug 22, 2016 edited

Update docs regarding new Java API (GraphHopperOSM, eclipse, etc)

Rough new structure of index.md:

Get Started

Link to GraphHopper Maps with picture

Link to Dev setup & User web setup

Introductory slides & videos

Web

web/quickstart.md
web/api-doc.md
core/deploy.md

Configuration

explain roughly config.properties or link to source with all parameters?
elevation.md

Translations

translations.md

Developers

Maven snippet, snapshots, IDE setup

changelogs

Technical

quickstart-from-source.md
technical.md
routing.md
weighting.md
location-index.md
low-level-api.md
ch.md
create-new-flagencoder.md

Android

Include picture

android/index.md
android/android-studio-setup.md

Windows

windows-setup.md

Eclipse

// hmmh I do not like it much that these docs are kind of a workaround where there has to be a better solution. Should we remove them completely?

eclipse-setup.md
eclipse-tomcat-setup.md

@karussell karussell added this to the 0.8 milestone Aug 22, 2016
@karussell karussell changed the title from Updated documentation to Update documentation Sep 12, 2016
@karussell karussell added a commit that referenced this issue Sep 12, 2016
@karussell karussell improved docs to match master #774 57015f8
@karussell
Member

I'm not that happy with the documentation right now. So if someone has an idea how we can:

  • link inline in the docs to up-to-date code example
  • set up a simpler/better structure e.g. separate in setup, preparation, routing, storage and deployment/web api or something
  • with a navigation/toc on the right side (have seen this somewhere here at github)

this would be awesome!

@karussell karussell added a commit that referenced this issue Sep 12, 2016
@karussell karussell no need to add a snapshot repo #774 dbe7292
@devemux86
Contributor

with a navigation/toc on the right side (have seen this somewhere here at github)

You mean the GitHub Wikis?

@karussell
Member

Yes. But I do not like github wikis (as we cannot refer to different versions) and so what we could do is use something similar we use for our Directions API docs: mkdocs

@kodonnell
Contributor

@karussell - is hosting on github required?

To get inline and up-to-date code documentation, my (little) experience is that it's best to have documentation directives in the code, and then auto-build the documentation (e.g. Sphinx). The reason being that if I'm e.g. developing a function, it's easy enough to just tweak the docstring, but I'm probably going to be too lazy to dig up the documentation file and tweak it.

You could get versioning by using readthedocs etc. I think that's per-release, but you can probably configure something so that the current state of the the master branch is also viewable.

Unfortunately, I'm not familiar enough with Java to recommend which documentation builder to use. (Though I see Sphinx has a java plugin.)

@karussell
Member
karussell commented Sep 12, 2016 edited

@kodonnell Thanks for the input.

@karussell - is hosting on github required?

It is important that all can read and edit it there, yes. But we could host it somewhere else as 'main entry'.

@kodonnell
Contributor

All the documentation source would be in git, so they can "read and edit it" - is that what you mean? It wouldn't be pretty (e.g. just markdown), but that's the point of the published version. That'd be a nice separation.

@karussell
Member

Yes, sounds like a similar approach like it would be with the linked mkdocs

The reason being that if I'm e.g. developing a function, it's easy enough to just tweak the
docstring, but I'm probably going to be too lazy to dig up the documentation file and tweak it.

Do you mean one could embed an example of code in the source code and it would 'somehow' appear in the docs?

@kodonnell
Contributor

Here's an example using javadoc:

It's not actually a very nicely presented one - you can usually configure how it looks, including having more generic helpful documentation, etc.

Do you mean one could embed an example of code in the source code and it would 'somehow' appear in the docs?

Yes, I think so. Examples are included above (source - line 1554 of above, doco).

I don't think mkdocs actually strips documentation out from code files.

@karussell karussell added a commit that referenced this issue Sep 12, 2016
@karussell karussell Revert "no need to add a snapshot repo #774"
This reverts commit dbe7292.
8a688b5
@karussell
Member

It's not actually a very nicely presented one - you can usually configure how it looks, including having more generic helpful documentation, etc.

That is the javadocs that we automatically create already. What I meant is a code snippet that we could directly integrate in the docs and would automatically refresh itself somehow :) if the referenced/underlying code changes.

Examples in javadocs have the same problem: they need to be maintained.

@karussell karussell added a commit that referenced this issue Oct 10, 2016
@karussell karussell improved documentation and gave index.md a new structure #774 2ac6c94
@karussell
Member

I've updated the documentation and introduced a new index.md

https://github.com/graphhopper/graphhopper/blob/master/docs/index.md

@karussell karussell removed this from the 0.8 milestone Oct 10, 2016
@karussell karussell added a commit that referenced this issue Oct 10, 2016
@karussell karussell updated docs and fixed typos and incorrect links #774 03b7be8
@kodonnell
Contributor

Examples in javadocs have the same problem: they need to be maintained.

Ah, now I understand. I'm not sure that there's any way to get round the fact that you have to maintain both separately. This strikes me as similar to unit tests: when the API changes you also have to "maintain" them separately. The key difference is that you're reminded/forced to do this when the tests don't pass (which Travis makes obvious). So, maybe there's a way to utilise unit tests to get the same sort of visibility to when documentation is out of date. For example, you could put documentation examples in tests, and have the documentation builder extract them (somehow). How you do this, I don't know = ) With a custom built documentation site it'd be "easy", but I'm not sure you'll find support in existing documentation builders.

@kodonnell
Contributor

I also considered extracting the examples from the doc strings, and then running them as unit tests (hence equivalent functionality to the above). I didn't mention it as I thought it'd be too messy (and I think it probably still is), though to be fair I just found a python equivalent, doctest, so thought I'd mention it.

@karussell
Member

This strikes me as similar to unit tests: when the API changes you also have to "maintain" them separately

Not really, as both is Java code and automatically refactored and test would fail to compile or run.

So, maybe there's a way to utilise unit tests to get the same sort of visibility to when documentation is out of date

Yes, somehow I want a unit test inside the documentation

though to be fair I just found a python equivalent, doctest, so thought I'd mention it.

Thanks for the pointer - interesting.

@kodonnell
Contributor

Not really, as both is Java code and automatically refactored and test would fail to compile or run.

Sure, IDE's can handle trivial refactoring, but much of the time you'll be stuck having to manually maintain them. The fact that tests fail / don't compile is my point: we want that for documentation.

@kodonnell
Contributor

The lack of clear documentation makes contribution for new developers difficult - see e.g. discussion here. So maybe this is higher priority?

@karussell
Member

This issue was more meant to create a better structure of the docs and also make examples in the documentation properly working even after refactoring.

Of course, improving documentation is always good and nice. The best thing is if new developers ask questions and get answers and then they condense their new knowledge into a pull request which we can together improve step by step. If I would just add more docs I would not know which parts are important to go into detail etc

@stefanholder
Contributor

the lack of clear documentation makes contribution for new developers difficult

For me, the lack of javadoc documentation made it quite hard. I think what we need are is a javadoc convention that applies to all new contributions. I would suggest to adopt the javadoc rules from the Google Java Style Guide. Should we discuss javadoc documentation in a separate issue?

@mprins
Contributor
mprins commented Dec 1, 2016

That is the javadocs that we automatically create already. What I meant is a code snippet that we could directly integrate in the docs and would automatically refresh itself somehow :) if the referenced/underlying code changes.

If/when using the Maven site plugin to generate html docs you can use code snippets; you add special comments to the source code and create a reference in the doc page source.
I've used this before but only on APT sourced pages, not sure how good the support of macro's is in other supported markup flavors...

@mprins
Contributor
mprins commented Dec 1, 2016

Apparently current versions of Doxia support macro's in markdown as well:

Macros are currently only supported for APT, Xdoc and FML formats. Starting with Doxia 1.7 (maven-site-plugin 3.5), macros are also supported for XHTML and Markdown. Macros are not (and probably will never be) supported by Confluence, Docbook and Twiki modules.

link

@karussell
Member
karussell commented Dec 1, 2016 edited

Should we discuss javadoc documentation in a separate issue?

Yes, and a rule like this sounds really good!

If/when using the Maven site plugin to generate html docs you can use code snippets;

Wow, this looks nice - now the question is: will it be refactored by e.g. IntelliJ or Netbeans :) ? Maybe we should create a separate 'docs module' with sources only for documentation purposes? E.g. how to do simple routing or fetch some results from a LocationIndex or link to already existing unit tests that show these tasks from the docs?

@karussell
Member

Also what to comment and what not is important and this is a good read: https://visualstudiomagazine.com/articles/2013/06/01/roc-rocks.aspx

  • It's important to communicate what the code should be doing. Comments should explain the "why" of the code and stop there.
  • What comments should never, ever do is explain how the code does its job.
@stefanholder
Contributor
stefanholder commented Dec 1, 2016 edited

Yes, and a rule like this sounds really good!

I just created #891, where we can further discuss javadoc documentation.

@mprins
Contributor
mprins commented Dec 1, 2016

also there's a doclet: https://github.com/jtulach/codesnippet4javadoc to get code snippets in the javadoc, eg from test cases into test javadoc if you will

@kodonnell
Contributor

Sounds good all round. One comment - when evaluating solutions, we may need to e.g. refer to some GH code from within map-matching, and I'm not sure if that'll be supported. That, or we e.g. merge map-matching into the GH repo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment