Open Bug 1679638 Opened 8 months ago Updated 4 months ago

Upgrade sphinx-js to 3.1

Categories

(Firefox Build System :: Documentation Infrastructure, enhancement)

enhancement

Tracking

(Not tracked)

ASSIGNED

People

(Reporter: zacnomore, Assigned: ahassou)

References

(Depends on 1 open bug, Blocks 1 open bug)

Details

Attachments

(1 file)

No description provided.
Depends on: 1679640
Summary: Upgrade spinx-js to 3.1 → Upgrade sphinx-js to 3.1

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.

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).

(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.

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.

(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.

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?

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.

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.

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.

Assignee: nobody → ahassou
Status: NEW → ASSIGNED
You need to log in before you can comment on or make changes to this bug.