1679638 - Upgrade sphinx-js to 3.1

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, enhancement)

Comment 1

[Amine]

Hello, can I take over this task? I am an outreachy applicant. Could I also get more details on what needs to be done? Thank you.

Comment 2

[Andrew Halberstadt [:ahal]]

Hello Amine, sorry I missed your comment. Feel free to use the needinfo feature to request information from me in the future.

This bug is about upgrading our dependency here:
https://searchfox.org/mozilla-central/source/tools/moztreedocs/requirements.in#46

We use pip-compile to generate the requirements.txt file in the same directory, so after modifying the .in file you can follow the linked docs to compile the .txt file. Then you'll need to test that you can generate the docs via ./mach doc without errors. We should also verify that some of the docs that use sphinx-js are still being rendered correctly (I'm unsure which ones use it off the top of my head).

Comment 3

[Amine]

(In reply to Andrew Halberstadt [:ahal] from comment #2)

Hello Amine, sorry I missed your comment. Feel free to use the needinfo feature to request information from me in the future.

This bug is about upgrading our dependency here:
https://searchfox.org/mozilla-central/source/tools/moztreedocs/requirements.in#46

We use pip-compile to generate the requirements.txt file in the same directory, so after modifying the .in file you can follow the linked docs to compile the .txt file. Then you'll need to test that you can generate the docs via ./mach doc without errors. We should also verify that some of the docs that use sphinx-js are still being rendered correctly (I'm unsure which ones use it off the top of my head).

I have tried to run ./mach doc, I get:

./mach: JSDoc==3.5.5 is required to build the docs but was not found on your system.
Please install it globally by running:

    $ mach npm install -g jsdoc@3.5.5

Bug 1498604 tracks bootstrapping jsdoc properly.
Bug 1556460 tracks supporting newer versions of jsdoc.

After doing that, I ran ./mach doc again and I get the same request to install jsdoc over and over again. Is this a known bug? I seem to be stuck here.

Comment 4

[Andrew Halberstadt [:ahal]]

Hm, no not a known issue as far as I know.

Are you running ”mach npm" rather than just "npm"? It needs to be installed to the bootstrapped node installation.

Comment 5

[Amine]

(In reply to Andrew Halberstadt [:ahal] from comment #4)

Hm, no not a known issue as far as I know.

Are you running ”mach npm" rather than just "npm"? It needs to be installed to the bootstrapped node installation.

Yes, I am running mach npm, I am also doing all of this inside of the "mozilla-unified" directory. I think it may be an issue where jsdoc is being installed in one area and mach_commands.py is checking for it in a different area. I was looking through code and I found this function in mach_commands.py:

def check_jsdoc(self):
        try:
            from mozfile import which

            exe_name = which("jsdoc")
            if not exe_name:
                return 1
            out = subprocess.check_output([exe_name, "--version"])
            version = out.split()[1]
        except subprocess.CalledProcessError:
            version = None

        if not version or not version.startswith(b"3.5"):
            return 1

Which seemingly checks if jsdoc is installed. This function is what causes the JSDoc==3.5.5 is required to build the docs but was not found on your system. pop-up to appear. So I am probably doing something wrong but I'm not sure what.

Comment 6

[Andrew Halberstadt [:ahal]]

Hmm, this bug just landed that removes the requirement for a globally installed jsdoc:
https://bugzilla.mozilla.org/show_bug.cgi?id=1498604

Maybe wait for it to merge to central (when it gets resolved fixed) and try again?

Comment 7

[Andrew Halberstadt [:ahal]]

Ah I see it got backed out. Hopefully it will land again soon. In the meantime you could try applying the patch in there locally to see if it helps.

Comment 8

[Amine]

The link you sent helped me fix it. Had to run PATH=$PATH:~/.mozbuild/node mach doc and that allowed me to succesfully build the docs.

Comment 9

[Amine]

Are there any unit tests I can run to verify that the firefox source docs are being generated properly? I've upgraded sphinx-js to version 3.1. I've managed to successfully run mach doc (albeit with many warnings). I clicked around and I can see that the docs are working but I'm not sure how to check if every page rendered properly.

Comment 10

[Amine]

Attachment: Bug 1679638 - Update sphinx-js to 3.1. r=sylvestre

Comment 11

[BugBot [:suhaib / :marco/ :calixte]]

The bug assignee didn't login in Bugzilla in the last 7 months.
:Sylvestre, could you have a look please?
For more information, please visit auto_nag documentation.

Comment 12

[Naoya Okamoto]

Hi, could I try to work on this bug? I'm not sure what sphinx-js is, but it says that this is a good first bug to work on, so I thought I would give it a shot. I'll try seeing what progress I can make.

Comment 13

[janneyt]

OK, I've actually updated the sphinx-js requirement, run pip-compile, and ./mach doc. There were a few random errors, I think because I have different versions of some things installed, but I can now browse my generated documents on localhost.

What's the best way to search for where sphinx-js is located? I'm brand-new to contributing here, so I'm still trying to figure out how to generate a patch and what the proper procedures are.

Comment 14

[Tawah Peggy]

Hello,
Just for your information, I am currently working on this bug. And will request a review soon enough.

Comment 15

[Sylvestre Ledru [:Sylvestre]]

done:
https://searchfox.org/mozilla-central/source/tools/moztreedocs/requirements.in#48