search

NeoGeographyToolkit / StereoPipeline

The NASA Ames Stereo Pipeline is a suite of automated geodesy & stereogrammetry tools designed for processing planetary imagery captured from orbiting and landed robotic explorers on other planets.
Apache License 2.0
479 stars 168 forks source link

Migrate README to markdown #292

Closed dshean closed 4 years ago

dshean commented 4 years ago

First attempt to reformat and reorganize the readme, with some minor modifications to the text. Should clean up the Documentation section to always point to latest pdf so people can view without downloading binaries - IRG site is not loading for me right now. Can potentially move the Zenodo badge (and any others) at top of README.

rbeyer commented 4 years ago

David, thanks for this, and I appreciate your enthusiasm. As we talked about, the plan is to begin the migration of the documentation 'source' from LaTeX to reStructuredText to enable us to build web and PDF documentation with Sphinx. So what I really want is to have a README.rst and not a README.md. That being said, the conversion isn't hard, and I'm not asking you to do it.

Do you mind if we keep this PR around for a little while, and I'll convert it to reStructuredText, and also fix up some other things that have been bothering me about the README for a while? We also have some elements that you took out that need to stay in (but I agree can be diminished) because NASA. This will mean that this PR ultimately won't get merged, but I'll absolutely use it as a basis for the changes.

dshean commented 4 years ago

Sounds good. Of course NASA.

In my opinion, updating the github README for modern repo presentation is a simple, easy task that should be possible independent of the larger doc overhaul. It's what most people will see. In my experience, most people just want a brief description, a nice banner image/logo, instructions on how to install, a short example with usage (stereo img1.tif img2.tif outdir/out; point2dem outdir/out-PC.tif), and links to quickstart and full doc. They probably won't make it to credits and license, at least not first-time users.

I also realized that this PR would modify the top-level plaintext README in the source. Not sure if we want to bundle parallel versions, or if a single README.rst would work.

rbeyer commented 4 years ago

Thanks again for this PR. I've merged a .rst version which should be good for us for a while. I've also started the conversion work on the Book from LaTeX to .rst, but I'm not going to push that for a while until I have some time to work out some kinks with the conversion.

dshean commented 4 years ago

Looks great!

Sounds good on the doc conversion plan. Let us know if we can help. We will continue assembling some interactive demos with bundled sample data, and hopefully can integrate down the line.