search

sisl / AutoViz.jl

Provides visualization tools for AutomotiveDrivingModels. Built on Cairo
Other
33 stars 9 forks source link

Docs examples #46

Closed mattuntergassmair closed 4 years ago

mattuntergassmair commented 4 years ago

improved examples in docs

work in progress, overlay tutorial still missing

as part of this PR, some defaults were changed:

I think the new defaults make more sense but this may be subjective and can be discussed / changed before closing the PR

coveralls commented 4 years ago

Coverage Status

Coverage increased (+5.3%) to 53.576% when pulling d37c011398e031bfac7b7f8d08d14246a36c0cca on mattuntergassmair:docs_examples into ecefe3aa71b5d5f18e5320fd4fb4c34af187f1f3 on sisl:master.

MaximeBouton commented 4 years ago

Thanks for doing this, two main comments:

1 - Are you re designing brand new tutorials? I had made a notebook for AutoViz 0.8 that you can take inspiration from 2 - the notebook was used in the tests, it would be nice to have all the examples run in the test suite. I don't think there is a nice way to do it though. Maybe the easiest is to just convert some of the examples into proper tests.

mattuntergassmair commented 4 years ago

Thanks for doing this, two main comments:

1 - Are you re designing brand new tutorials? I had made a notebook for AutoViz 0.8 that you can take inspiration from 2 - the notebook was used in the tests, it would be nice to have all the examples run in the test suite. I don't think there is a nice way to do it though. Maybe the easiest is to just convert some of the examples into proper tests.

The examples are heavily inspired by the notebooks that were there in the notebooks folder (in fact, I exported them first and used them as a basis to start from). I tried not to lose any information, but felt that it made sense to restructure the examples significantly and focus on different aspects in different tutorials. For example, the camera tutorial now shows all the available cameras, and finally implements a custom camera. I just had a look at the notebook you mentioned, for some reason it wasn't there on the branch that I forked from. I'll make sure to integrate all the information from there in the docs (section on overlays is still work in progress)

mattuntergassmair commented 4 years ago

Thanks for doing this, two main comments:

1 - Are you re designing brand new tutorials? I had made a notebook for AutoViz 0.8 that you can take inspiration from 2 - the notebook was used in the tests, it would be nice to have all the examples run in the test suite. I don't think there is a nice way to do it though. Maybe the easiest is to just convert some of the examples into proper tests.

As for testing, how does it work at the moment? Is the documentation built automatically when we push changes? Could we make it fail when there are errors in @examples (currently only warnings). Or is there a way to convert *.md files to *.jl files programatically, such that we could use them for tests?

If none of the above works we should consider writing tests separately but I'm afraid there may be code duplication - would be nice if we could avoid that with one of the aforementioned options.

MaximeBouton commented 4 years ago

Yes it is only warnings for now. With the notebooks, the test suite was including the notebooks and running them so if there was a bug in the notebook it would break the test. Another extra is that it would reflect in the code coverage. Maybe we can ask on the documenter repo if there is a way to include the examples in the tests.

MaximeBouton commented 4 years ago

This is super neat!! thanks a lot

MaximeBouton commented 4 years ago

Is this ready to merge? thanks for the work!