ngboost
ngboost copied to clipboard
stanfordmlgroup
ngboost.readthedocs.io
Hello, I thought it would be helpful to the package to have a page on readthedocs.io. The main reason I think it's a good idea is to get some kind of docs related to the api up similar to https://xgboost.readthedocs.io/en/latest/python/python_api.html. The scaffold can be created using: https://docs.readthedocs.io/en/latest/intro/getting-started-with-sphinx.html. This would create a .rst file here: https://ngboost.readthedocs.io/en/latest/. Once that is up I'd be happy to contribute to the documentation by way of a pull request. Thanks, Ryan
Hi @ryan-wolbeck, thanks for the suggestion and for offering to expand the docs! Right now the only "docs" are what's in the user guide and what's in the docstrings for the user-facing constructors and methods in the package.
Is your thought that these two sources aren't formal enough in their description of the API? My impression is that users tend to get more out of vignettes (like the user guide) than from API specs, but I also see why you might want those details somewhere besides the docstrings. On the other hand, it would also be nice to keep everything together in one place. To that end, would it be possible to host the current user guide through readthedocs.io as well? Those pages are generated with jupyter book which I really like because all the I/O is exactly what the user's experience is. Ideally we'd be able to keep using that. Jupyter books also uses sphinx so I'd hope there's a way to make that work.
It would also be nice to keep a clean link between docstrings and whatever ends up in readthedocs.io. Do you have any ideas for auto-generating docs from docstrings or vice-versa?
Hey @alejandroschuler, Yeah I think to the casual user the documentation and just he user guide is sufficient but if you'd like to look at say what the base default learner is you have to dig to get there i.e. here : https://github.com/stanfordmlgroup/ngboost/blob/master/ngboost/learners.py Or to figure out what the defaults are when you call things like NGBRegressor you have to filter through https://github.com/stanfordmlgroup/ngboost/blob/master/ngboost/api.py and look at the init which for a user like myself isn't difficult to figure out but I think it would be more user friendly to be explicit in the docs.
On the second point I don't think it has to be via the route I suggested if we can get all that content in the jupyter books and mirror it to read the docs I think that would be okay. Personally I had a bit of a struggle to edit the jupyter files (locked) when cloning this repo out to make the pull request for the typo in the pip install https://github.com/stanfordmlgroup/ngboost/pull/148 and I wasn't able to easily render those changes locally to figure out what other files needed to be run to make the full change that @tonyduan made here https://github.com/stanfordmlgroup/ngboost/commit/142453243984444915d6ad3bd0dd3f70238281a4 So maybe the alternative is to just write a simple contributor guide to say to modify the docs make changes here >> run the make file or w/e the submit the pr. I also don't know about how to pub the jupyter book to readthedocs generally so I think more research is warranted there.
Thanks, Ryan
@ryan-wolbeck well put! I'll try to do some digging and get things set up in a way that makes sense. Might have something by the weekend but in case I don't please feel free to start some docs as .md or whatever you like and we can transfer them over once the infrastructure is ready. And, of course, please feel free to make PRs that edit/improve the docstrings as well.
On the other hand, it would also be nice to keep everything together in one place. To that end, would it be possible to host the current user guide through readthedocs.io as well? Those pages are generated with jupyter book which I really like because all the I/O is exactly what the user's experience is.
FYI, Jupyter Book projects can now be hosted on Read the Docs, see https://jupyterbook.org/publish/readthedocs.html (still to be released)
