search

petermr / pygetpapers

a Python version of getpapers
Apache License 2.0
78 stars 9 forks source link

Comments on documentation #36

Open ml-evs opened 2 years ago

ml-evs commented 2 years ago

Final issue of the day!

  1. The auto-generated side of the docs on readthedocs are not that useful in places, e.g., https://pygetpapers.readthedocs.io/en/latest/crossref.html. It might just be that the docstring format needs to be tweaked.
  2. It also seems that the docs for the rxiv submodule are missing from readthedocs, presumably because of an issue with the sphinx build.
  3. The "hand-written" documentation (based on your README, I think?) looks great! You might consider turning some sections into subsections, e.g. Installation -> Way one/way 2 to make it easier to navigate.
  4. For the JOSS paper itself, the reviewers are asked to run through the tutorials, so it's probably worth checking that these work with the latest code (maybe even added as test cases, if possible). Again, it might be worth reorganizing this slightly to make it easier to navigate. For example, I can't find the "Tutorials" section on readthedocs, but I see that it is present in your README -- in fact I now see that they are two separate files (and also a second rst version of the README). You might consider unifying this into one file, or as is commonly done, importing the README in your docs build.
ayush4921 commented 2 years ago

Hi @ml-evs , I fixed the readme being there in two versions (rst and md). The readthedocs now is automatically updated with every push. I have also added tutorials there.

ml-evs commented 2 years ago

Great job! The docs look much better -- really like the addition of "Developer docs" too (I don't remember seeing them before).

From the above, I think my point 3. still stands as the sidebar is a bit messy. Perhaps just demoting some of your section headings in the README/index would work? e.g.

# What is pygetpapers
## History
## Supported Formats
## Repository Structure
## ...
# Installation
# Usage
## What is CProject?
# Tutorials

It also looks like the API docs appear twice in the sidebar. I think all you have to do is move them to a subfolder and then adjust your links from index.rst.

kjappelbaum commented 2 years ago

Some minor comments I'd like to add on top of Matthew's:

But, overall, the documentation looks good and useful!

petermr commented 2 years ago

Thanks, I was thinking that other parts of the paper (history and some of the output) might also go onto the site rather than in the paper.

On Sun, Jun 5, 2022 at 9:03 PM Kevin Jablonka @.***> wrote:

Some minor comments I'd like to add on top of Matthew's:

  • I like to keep the README file minimal and then provide examples/more details in dedicated documentation sections. I feel that putting all the information into one file can be overwhelming (and a nice sphinx site can be easier to search)
  • you can consider making some of the examples easier to run without installation - e.g. providing a Colab or Binder link

But, overall, the documentation looks good and useful!

— Reply to this email directly, view it on GitHub https://github.com/petermr/pygetpapers/issues/36#issuecomment-1146874731, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAFTCSYLV6HIPDCTJGUDBXTVNUBYDANCNFSM5O7FRNPA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

-- Peter Murray-Rust Founder ContentMine.org and Reader Emeritus in Molecular Informatics Dept. Of Chemistry, University of Cambridge, CB2 1EW, UK

khinsen commented 2 years ago

Something I noted in the README:

"A CProject is a directory structure that the AMI toolset uses to gather and process data. Each paper gets its folder. "

What is "the AMI toolset"? Are there other tools than pygetpapers that work with the same directory structure? If so, links to those tools would be more than welcome.

petermr commented 2 years ago

Thanks very much Konrad,

Yes we have a large stack in Java at https://github.com/petermr.ami3 . Ayush, could you please edit the docs to include this link?

On Tue, Jun 7, 2022 at 4:37 PM Konrad Hinsen @.***> wrote:

Something I noted in the README:

"A CProject is a directory structure that the AMI toolset uses to gather and process data. Each paper gets its folder. "

What is "the AMI toolset"? Are there other tools than pygetpapers that work with the same directory structure? If so, links to those tools would be more than welcome.

— Reply to this email directly, view it on GitHub https://github.com/petermr/pygetpapers/issues/36#issuecomment-1148837115, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAFTCS7OP3JGJ55Y22FERFTVN5UDLANCNFSM5O7FRNPA . You are receiving this because you commented.Message ID: @.***>

-- Peter Murray-Rust Founder ContentMine.org and Reader Emeritus in Molecular Informatics Dept. Of Chemistry, University of Cambridge, CB2 1EW, UK

ayush4921 commented 2 years ago

Done sir

ayush4921 commented 2 years ago

Some minor comments I'd like to add on top of Matthew's:

  • I like to keep the README file minimal and then provide examples/more details in dedicated documentation sections. I feel that putting all the information into one file can be overwhelming (and a nice sphinx site can be easier to search)
  • you can consider making some of the examples easier to run without installation - e.g. providing a Colab or Binder link
  • I would consider putting the contribution guidelines into their own file

But, overall, the documentation looks good and useful!

Thanks a lot for the recommendations. I have added contributions file separately and have added the link to the file in the readme.

I have also added a colab to make installation easier to understand