Replacing doclets.io

chinmay3199 · March 26, 2020, 2:36pm

I was trying to find a replacement of defunct doclets.io and the best that I could find was GitHub - andstor/jsdoc-action: GitHub Action to build JSDoc documentation

To get my hands on this I made an example repo but I am unable to run the action on this. I might be having trouble with my config.json file or the yml.file (this is unlikely to me). I would be glad if you could do any help. Thanks!!

mr_monkey · March 26, 2020, 3:31pm

I’m not sure what to make of this, or how to help you.
To me the yaml and conf files look fine, and this is an issue of missing dependency (thrown here in the jsdoc package: https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc-core/lib/name.js#L7).
I don’t know why the package isn’t installed properly.

Did you try rerunning the build and/or pushing a commit to master to trigger another one?

Otherwise I would take it the jsdoc-action or jsdoc repos and open an issue there.

I do note that jsdoc-action have a github workflow file to update the node_modules. Maybe it’s related?

github.com

andstor/jsdoc-action/blob/master/.github/workflows/node_modules.yml

name: Update node_modules

on:
  push:
    branches:
      - 'develop'
    paths:
      - 'node_modules/**'
      - 'package.json'
      - '.github/workflows/node_modules.yml'

jobs:
  prune:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Set up Node
        uses: actions/setup-node@v1
      - name: Prune prod

This file has been truncated. show original

In it, I see an action actions/setup-node that you might be missing.
Maybe this will help : https://help.github.com/en/actions/language-and-framework-guides/using-nodejs-with-github-actions#installing-dependencies

chinmay3199 · March 27, 2020, 8:43am

Hi @mr_monkey

I have worked around with this github action and I am planning to use as a replacement for doclets.io

I have made an example repo, and generated the following webpage for this:
https://chinmay-kothari.github.io/DocsExample/

Let me know what you think about it, and if it is fine shall I start writing my proposal.

Thanks

mr_monkey · March 27, 2020, 5:04pm

The example looks pretty good to me!
This looks like a viable way to host live docs, nicely done.

Now do remember that the GSOC proposal cannot be only about hosting the docs.
At this point I’m not sure how to gage your capacity to write good documentation nor your level of understanding of the BookBrainz schema and codebase, aspects that are going to be necessary if you are to improve the user guides and code documentation.

chinmay3199 · March 27, 2020, 5:40pm

Thanks for the review.

Well what can I say now on that
I was also planning to increase our code coverage as mentioned in Project Statement. For that, I would be writing unit tests for different parts of our code. I think that along with hosting the docs and writing the complete user-developer guide could be a GSOC project.

There are some tickets in JIRA regarding the unit tests eg. BB-68, maybe I can solve them to contribute a bit before the selection process.

Please let me know if that could be a GSOC project or not.

Thanks again!

mr_monkey · March 27, 2020, 5:57pm

I think the whole lot makes a GSOC project.
I think there should be goals set for coverage percentage increase (as a way to quantify progress), and some details on what areas will be covered in the user docs.

A skeleton of the user docs would be a good way to show where you are going and
more concrete talking points.

Any way you can show that you know how to write good tests would work; picking any part of the codebase and writing unit tests would certainly be a way.
The issue you mention (BB-68) refers to an old repository and I haven’t updated them, my bad !

chinmay3199 · March 27, 2020, 6:25pm

To get a specific number for code coverage, I would need sometime to go through all test file and find where the work can be done.

I can share with you a draft on what areas I will cover in user docs along with a prototype of how the things will be arranged in it.

Also bookbrainz uses readthedocs to host the docmentations while musicbrainz shows them on the website itself. Should we go ahead with the our current template or should we also make all the documentation available on the website.

I will get back to you a proposal covering the points you mentioned along with the user prototype.

Thanks

mr_monkey · March 28, 2020, 10:21am

For the user docs, rather than a prototype or demo, I’d like to see an index or sitemap.
That’s what I meant by skeleton: I’d like you to have a good idea of what the contents are going to be before starting any prototype.
What I want to assess is your capacity to be somewhat autonomous and find by yourself the problems that need solving, in this case what needs to be documented and described to the user.

chinmay3199 · March 28, 2020, 7:17pm

Hi @mr_monkey,

I had gone through the Bookbrainz thoroughly and I think these are problems that need to be addressed in the user guide. Attached the sitemap on how I plan to lay out the problems.

I have written the details on each in the here.

Please let me know what you think of it. Thanks!

mr_monkey · October 16, 2020, 11:22am

Hi @chinmay3199!
I wanted to say a big thank you for your tests, thanks to which I was able to pretty easily automatically deploy the JSDocs using Github actions !
Here’s what it looks like so far:
https://bookbrainz.github.io/bookbrainz-site
https://bookbrainz.github.io/bookbrainz-data-js