Suggestions for the README

[RonaldEnsing]

Related to openjournals/joss-reviews#3471.

I'd recommend to add links to refer to some things mentioned in the readme. For example:

• A link to the pypi website of pointcloudset: https://pypi.org/project/pointcloudset/.
• A link to the HTML documentation: https://virtual-vehicle.github.io/pointcloudset/.

No default tag latest is defined for the https://hub.docker.com/repository/docker/tgoelles/pointcloudset image, so a docker pull tgoelles/pointcloudset will not work. A tag would need to be specified by the user. Is this done intentionally? In that case I think that it would be good to write the exact docker pull command in the readme.

The Quickstart example shows a code snippet that refers to rosbag_file.bag and lasfile.las. Are these files available somewhere? Would it be possible to include a quickstart example with existing example files - and ideally - some example output that includes the visualizations as shown in the README?

[tgoelles]

Yes links are certainly a good idea.

Yes I avoided the latest tag since it can cause some confusion. But, I think I can easily add it to github actions to tag it both with the version name and latest.

The quickstart example is only there to give a quick idea what the API looks like. For working examples of code please see usage.ipynb. Do you think that the user expects working examples in the README or just a general idea of what the API looks like?

I also want to change the sphinx setup to run the notebooks so that notebook is populated with results and plots. This would also improve the html documentation.

[RonaldEnsing]

Yes I avoided the latest tag since it can cause some confusion. But, I think I can easily add it to github actions to tag it both with the version name and latest.

I think that would be nice. I expect that most users will do a docker pull without specifying or looking into versions and expect it to work. Especially when they are only exploring the package to see if it is useful to them.

Do you think that the user expects working examples in the README or just a general idea of what the API looks like?

I'd expect a working example. If the quickstart is only meant to show a general idea, then what general idea do you want to show specifically? It only shows the file I/O. I think it would be nice if a quickstart allows someone to reproduce the Figures under 'Features' in the README. If that would make the README too cluttered, then maybe a link to a notebook on how to produce these Figures?

I also want to change the sphinx setup to run the notebooks so that notebook is populated with results and plots. This would also improve the html documentation.

Sounds good! I think the notebooks are somewhat 'hidden' in the docs directory. Maybe it would help to add a link from the README to the notebooks to increase the discoverability of the notebooks.

[tgoelles]

We fixed everything except a problem with updating documentation from notebooks remains. See issue #12