Incorrect syntax highlighting

[sobester]

Expected Behavior

Syntax highlighting in code snipets in docstring

Actual Behavior

Syntax highlighted beautifully in some cases, partially in others (only some keywords, etc.), not at all in yet others.

Steps to Reproduce

Here is an example function where the resulting HTML has the code all in grey:

def tw2pw(thrusttoweight, speed, etap):
    """Converts thrust to weight to power to weight (propeller-driven aircraft)

    `PARAMETERS`
    ------------

    `thrusttoweight` : thrust to weight ratio (non-dimensional)

    `speed`: speed (in m/s if output in Watts / Newton is required)

    `etap`: propeller efficiency (non-dimensional)

    `RETURNS`
    -----------

    power to weight ratio (in W/N if speed is in m/s)

    `SEE ALSO`
    ------------
    ``powerrequired``

    `NOTES`
    ---------
    A note on units. If the input speed is in m/s, the other two inputs being
    non-dimensional, the output product is also in m/s, which is equal to W/N
    (W / N = (J/s) / N = (Nm/s) / N = m/s).

    `EXAMPLE`
    ---------

    ------------
        #!python
        import constraintanalysis as ca
        import atmospheres as at
        import unitconversions as co

        designbrief = {'stloadfactor': 2, 'turnalt_m': 3050, 'turnspeed_ktas': 140}

        etap = {'turn': 0.85}

        designperformance = {'CLmaxclean': 1.45, 'CDminclean': 0.02541,
                             'etaprop': etap}

        designdef = {'aspectratio': 10, 'sweep_le_deg': 2,
                     'sweep_mt_deg': 0, 'bpr': -1}

        TOW_kg = 1500

        designatm = at.Atmosphere()
        concept = ca.AircraftConcept(designbrief, designdef,
                                     designperformance, designatm)

        wingloading_pa = 1000

        twreq, _, _ = concept.twrequired_trn(wingloading_pa)

        turnspeed_mpstas = co.kts2mps(designbrief['turnspeed_ktas'])

        pw_trn_wpn = ca.tw2pw(twreq, turnspeed_mpstas, etap['turn'])
        pw_trn_hpkg = co.wn2hpkg(pw_trn_wpn)
        p_trn_hp = pw_trn_hpkg * TOW_kg

        print(p_trn_hp)

    ---
        #!python
        318.691213406
    """
    return thrusttoweight * speed / etap

Other, seemingly very similar docstrings in the same .py file are highlighted very nicely, for example:

    def twrequired_trn(self, wingloading_pa):
        """Calculates the T/W required for turning for a range of wing loadings

        `PARAMETERS`
        ------------

        `wingloading_pa` : float or numpy array, list of wing loading values in Pa.

        `RETURNS`
        -----------

        `twratio` : array, thrust to weight ratio required for the given wing loadings.

        `clrequired` : array, lift coefficient values required for the turn (see notes).

        `feasibletw`: as twratio, but contains NaNs in lieu of unachievable (CLmax exceeded) values.

        `SEE ALSO`
        ------------
        ``twrequired``

        `NOTES`
        ---------
        1. Use `twrequired` if a full constraint analysis is desired, as this integrates
        the take-off, turn, climb, cruise, and service ceiling constraints, as well as
        computing the combined constraint boundary.

        2. At the higher end of the wing loading range (low wing area values) the CL required
        to achieve the required turn rate may exceed the maximum clean CL (as specified in the
        `CLmaxclean` entry in the `performance` dictionary argument of the `AircraftConcept`
        class object being used). This means that, whatever the T/W ratio, the wings will stall
        at this point. The basic T/W value will still be returned in `twratio`, but there is
        another output, `feasibletw`, which is an array of the same T/W values, with those
        values blanked out (replaced with NaN) that cannot be achieved due to CL exceeding
        the maximum clean lift coefficient.

        `EXAMPLE`

        Given a load factor, an altitude (in a given atmosphere) and a true airspeed, as well as
        a set of basic geometrical and aerodynamic performance parameters, compute the necessary
        T/W ratio to hold that load factor in the turn.
        ------------
            #!python
            import atmospheres as at
            import constraintanalysis as ca
            import unitconversions as co

            designbrief = {'stloadfactor': 2, 'turnalt_m': co.feet2m(10000), 'turnspeed_ktas': 140}

            etap = {'turn': 0.85}

            designperformance = {'CLmaxclean': 1.45, 'CDminclean':0.02541, 'etaprop': etap}

            designdef = {'aspectratio': 10.12, 'sweep_le_deg': 2, 'sweep_mt_deg': 0, 'bpr': -1}

            designatm = at.Atmosphere()

            concept = ca.AircraftConcept(designbrief, designdef,
            designperformance, designatm)

            wingloadinglist_pa = [1250, 1500, 1750]

            twratio, clrequired, feasibletw = concept.twrequired_trn(wingloadinglist_pa)

            print('T/W:               ', twratio)
            print('Only feasible T/Ws:', feasibletw)
            print('CL required:       ', clrequired)
            print('CLmax clean:       ', designperformance['CLmaxclean'])

        ---
            #!python
            T/W:                [ 0.19920641  0.21420513  0.23243016]
            Only feasible T/Ws: [ 0.19920641  0.21420513         nan]
            CL required:        [ 1.06552292  1.2786275   1.49173209]
            CLmax clean:        1.45

        """

        if self.turnspeed_ktas == -1:
            turnmsg = "Turn speed not specified in the designbrief dictionary."
            raise ValueError(turnmsg)

        if self.stloadfactor == -1:
            turnmsg = "Turn load factor not specified in the designbrief dictionary."
            raise ValueError(turnmsg)

        wingloading_pa = actools.recastasnpfloatarray(wingloading_pa)

        # W/S at the start of the specified turn test may be less than MTOW/S
        wingloading_pa = wingloading_pa * self.turn_weight_fraction

        twratio, clrequired = self.thrusttoweight_sustainedturn(wingloading_pa)

        # What SL T/W will yield the required T/W at the actual altitude?
        temp_c = self.designatm.airtemp_c(self.turnalt_m)
        pressure_pa = self.designatm.airpress_pa(self.turnalt_m)
        density_kgpm3 = self.designatm.airdens_kgpm3(self.turnalt_m)
        turnspeed_mps = co.kts2mps(self.turnspeed_ktas)
        mach = self.designatm.mach(turnspeed_mps, self.turnalt_m)
        corr = self._altcorr(temp_c, pressure_pa, mach, density_kgpm3)

        twratio = twratio / corr

        # Map back to T/MTOW if turn start weight is less than MTOW
        twratio = twratio * self.turn_weight_fraction

        # Which of these points is actually reachable given the clean CLmax?
        feasibletw = np.copy(twratio)
        for idx, val in enumerate(clrequired):
            if val > self.clmaxclean:
                feasibletw[idx] = np.nan

        if len(twratio) == 1:
            return twratio[0], clrequired[0], feasibletw[0]

        return twratio, clrequired, feasibletw

I cannot figure what I'm doing right in one but not in the other...

Many thanks for the great tool.

Additional info

• pdoc version: current

[kernc]

Can you attach the HTML output file? I'll wager it's the highlighting engine auto-detecting the wrong language.

[sobester]

here is the link to the html: https://www.dropbox.com/s/p1qoke0ko0xcy1l/constraintanalysis.html?dl=0

[kernc]

The issue appears to be that Highlight.js for some reason recognizes your code snippet as Makefile code. You can force the code language using fenced-code blocks with language specification instead of indented blocks, i.e.:

EXAMPLE
-------

```python
import constraintanalysis as ca
import atmospheres as at
import unitconversions as co
...

```

Other than that, this looks like an upstream issue. Filed as highlightjs/highlight.js#1976.

[sobester]

The fence code blocks method seems to do the trick! Many thanks.