Comments (11)
This looks great: wonderfully done! Once merged to master
, feel free to close, and I'll consider online API docs completed for the purposes of JOSS review.
from astropaint.
JOSS reviewer here! (openjournals/joss-reviews#2608)
I strongly suggest you implement some public-facing API documentation on RTD in addition to the (very impressive) information already on the repo's README. If neither your nor other repo developers have done this before and you feel lost, I may be able to offer some help.
from astropaint.
This is a great suggestion Zach. I started looking into sphinx and RTD a while ago to implement the API documentation but I found it a bit more complicated than I had originally anticipated. Unfortunately, I still haven't had a chance to look into it again but as you can see in the issue description we do "Desperately need help with this"! :)
We sincerely appreciate and welcome your kind offer to help with the documentation. Please let me know how you would like to proceed.
from astropaint.
Hi again, I had an opportunity to start some docs stubs in a fork. These I just created using sphinx's native tools, basically following these guides. If you want, I can make a pull request into this repo, and hand what I have to you. This choice, I think, will make this particular issue go quicker, since this package is on the smaller side. Long-run, you should play around with starting docs from nothing, but this may not be the place for that, if you're feeling time-crunched 😄.
Let me know if I should make a PR: if so, I can refer you to some next steps.
from astropaint.
Thank you so much for putting this together, Zach! I really appreciate the effort. It looks great.
We can definitely go ahead with a PR on this, but I see that your changes have been added to master
on your fork. We develop new features on separate branches which after completion are merged into develop, then tested, then merged into master. Ideally, if you could go back in your commit history on master and rebase to a docs
branch and submit a PR from zpace:docs
to syasini:docs
it would be great. I understand if this is too much trouble though.
I have a followup question about developing the docs: Is there a way to automagically extract functions and their docstrings and transfer them to the docs template? I was under the impression that sphinx somehow facilitates this process but last time I played around with it I didn't find a way to do this.
Another note about the docs: I don't know how this will work logistically, but if you'd like to develop and contribute to the documentation we would be more than happy to add you to the collaboration and the paper. We can discuss this via email separately if you want.
from astropaint.
Ok, I'll rebase to docs
and submit a PR this afternoon. At that point, you can start inserting content into docs/index.rst
. This should entail mostly copy-pasting or linking content from your repo's README.md, which already has lots of the info that the docs index should have. Really, you're most of the way there already!
Coming to readthedocs integration, there's some coverage of that in one of those tutorials I linked above. For a smallish package like this, the process should be somewhat straightforward.
As for going docstrings => docs, there is a command, sphinx-apidoc
that manages that functionality. That's one of those things I wish was more obvious, so don't feel bad for missing it. As part of the barebones documentation, I've gone ahead and run that command, which put a handful of .md files in docs/source
, which should be linked in the docs' TOC. Anytime you add another module, you'll simply rerun that command to generate the markdown!
from astropaint.
Oh, also, could you create a docs
branch in the base repo? Looks like I cannot do that myself.
from astropaint.
Oh nice! That was quick. I appreciate it. And thanks for your encouragement. I'll definitely check out the tutorials and add the contents of the README file to index.rst, but maybe later next week.
I just created a new docs
branch. I'll also go ahead and give you access to the repo just in case.
from astropaint.
ok, this took a lot longer than I expected but it's finally done! :)
I had to convert the README from md
to rst
so sphinx can read it—I tried an automated format converter but it didn't work well so I ended up rewriting the code blocks and image sections.
I also linked it to readthedocs which you can see here.
This is only reading the docs
branch, but I'll recompile it after I merge everything to master
. Let me know if you have any comments.
Thanks again for your help and encouragement.
from astropaint.
Great! I will merge this to master
soon.
Thanks again for your help, Zach 🙏
from astropaint.
Merged the docs into master
and adde a link to the documentation in the README file as well as a docs badge .
from astropaint.
Related Issues (20)
- Selective updating on catalog parameters HOT 1
- parallelize the redshift calculations in Catalog()
- Fix the units of M_200c in Websky_lite and Websky_2x2
- Dataset Download Module HOT 3
- Einasto Profile
- Factorize NFW profiles
- Add tSZ to Battaglia16
- Add more tests
- Check kSZ C_ell against WebSky
- Change n_cpus manually HOT 1
- Paint qSZ using Line Integral Convolution HOT 1
- cut mask (experiment footprint) based on input keyword
- add LICENSE file HOT 3
- painter.spray(..., parallel=True) fails ("unexpected keyword argument") HOT 4
- public documentation: Statement of need HOT 3
- GitHub Actions Workflow HOT 2
- scipy requirement HOT 3
- parallel perfomance HOT 4
- example name change HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from astropaint.