search

ml-struct-bio / cryodrgn

Neural networks for cryo-EM reconstruction
http://cryodrgn.cs.princeton.edu
GNU General Public License v3.0
286 stars 74 forks source link

Nuke the sphinx docs? #350

Open zhonge opened 4 months ago

zhonge commented 4 months ago

We moved our documentation to gitbook (preference for a WYSIWYG editor): https://ez-lab.gitbook.io/cryodrgn/

@michal-g was going to look into possibly revisiting sphinx docs, but pending that, we should remove the sphinx docs (docs) from the repo and turn off the automatic deployment/ delete the gh-pages branch.

michal-g commented 2 months ago

Having gained admin access I took another look at our GitHub deployments and did some cleaning up and polishing for #366 — for the Sphinx docs in particular I made them only deploy when a new tag is pushed to main, whereas previously they deployed whenever a new tag was pushed to any branch. Since main is protected and requires approvals and checks before branches or commits (and thus any tags on them) are merged to it, these doc deployments will now happen much more rarely, and only upon the kind of action usually associated with a new version release as opposed to whenever anyone decides to create a new tag.

I also looked at how sphinx.ext.autodoc works — it could be useful for auto-generating help pages for the docstrings used in our commands for people who don't want to use the command-line interface (-h) to access these help messages. We are in the process of making better, more complete versions of these docstrings (see e.g. commands_utils.clean) and it would be nice if users could read them in a browser and not a terminal window!

Since we can make these doc deployments less messy and more useful, and Sphinx actually does a good job of segregating the document data (docs/) and commit history of generated content (gh-pages branch) from the rest of our repo, for now I am in favour of giving Sphinx another go! It can be used alongside a WYSIWYG editor like gitbook for more API-type auto-generated content as opposed to manually-generated tutorials and demos.

zhonge commented 1 month ago

Using sphinx to auto-generate help pages for docstrings in the commands/API seems helpful, but I do think gitbook is much easier for writing tutorials/user guides. Should we have both?

michal-g commented 1 month ago

Yup, just to clarify:

It can be used alongside a WYSIWYG editor like gitbook for more API-type auto-generated content as opposed to manually-generated tutorials and demos.

is a recommendation for what we should try! I will be working on cleaning up the gitbook content and will also continue trying to produce something more useful from the Sphin