Git Product home page Git Product logo

sphinxify's Introduction

sphinxify

Convert Javadoc and Doxygen to Sphinx docstrings.

Why?

The RobotPy project ports Java libraries to Python.

A converter was originally written in HTML + JavaScript, but then the need to be able to programmatically convert doc comments arose.

This also makes it easier to use in certain editors such as vim...

Usage

Run sphinxify and give it a Javadoc comment. It will keep reading until EOF.

If a Java function prototype is also given, sphinxify will also output a Python type-hinted function signature.

You can also run sphinxify server and it will pop up a browser that you can use to run sphinxify on the input also.

There is also a sphinxify yaml mode for the robotpy-ctre.

sphinxify's People

Contributors

auscompgeek avatar pre-commit-ci[bot] avatar virtuald avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

Forkers

virtuald

sphinxify's Issues

Escape words that end in _

DataLogManager needs this. I don't really want to copy/paste that whole thing, since it's still a new class and I'm sure the docs will be updated at some point. Here's the change I would like.. seems to work.

- ...target storage, FRC_ log files are deleted...
+ ...target storage, FRC\\_ log files are deleted... 

Doesn't handle @note correctly?

  /**
   * Create a new entry for the topic, with specific type string.
   *
   * Entries act as a combination of a subscriber and a weak publisher. The
   * subscriber is active as long as the entry is not destroyed. The publisher
   * is created when the entry is first written to, and remains active until
   * either Unpublish() is called or the entry is destroyed.
   *
   * @note It is not possible to use two different data types with the same
   *     topic. Conflicts between publishers are typically resolved by the
   *     server on a first-come, first-served basis. Any published values that
   *     do not match the topic's data type are dropped (ignored), and the entry
   *     will show no new values if the data type does not match. To determine
   *     if the data type matches, use the appropriate Topic functions.
   *
   * @param typeString type string
   * @param defaultValue default value used when a default is not provided to a
   *        getter function
   * @param options publish and/or subscribe options
   * @return entry
   */

Translates to:

"""Create a new entry for the topic, with specific type string.

        Entries act as a combination of a subscriber and a weak publisher. The
        subscriber is active as long as the entry is not destroyed. The publisher
        is created when the entry is first written to, and remains active until
        either Unpublish() is called or the entry is destroyed.

        .. note:: I
        topic. Conflicts between publishers are typically resolved by the
        server on a first-come, first-served basis. Any published values that
        do not match the topic's data type are dropped (ignored), and the entry
        will show no new values if the data type does not match. To determine
        if the data type matches, use the appropriate Topic functions.

        :param typeString:   type string
        :param defaultValue: default value used when a default is not provided to a
                             getter function
        :param options:      publish and/or subscribe options

        :returns: entry
        """
        ```

HTML stripping leaves extra spaces?

The following comment as parsed by robotpy-build:

  /**
   * Get the raw output ratio of the duty cycle signal.
   *
   * <p> 0 means always low, an output equal to
   * GetOutputScaleFactor() means always high.
   *
   * @return output ratio in raw units
   */

Transformed into

      .def("getOutputRaw", &frc::DutyCycle::GetOutputRaw, release_gil(),
      "Get the raw output ratio of the duty cycle signal.\n"
      "\n"
      " 0 means always low, an output equal to\n"
      "GetOutputScaleFactor() means always high.\n"
      "\n"
      ":returns: output ratio in raw units")

There's an extra space before the 0.

bug

>>> import sphinxify
>>> input = '*\n* Sends an error to the driver station.\n*\n* @param isError   true for error, false for warning\n* @param errorCode the error code\n* @param isLVCode  true for a LV error code, false for a standard error code\n* @param details   the details of the error\n* @param location  the file location of the errror\n* @param callstack the callstack of the error\n* @param printMsg  true to print the error message to stdout as well as to the\n* DS\n*/'
>>> sphinxify.process_raw(input)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "sphinxify.py", line 196, in process_raw
    return process_doc(s[0])
  File "sphinxify.py", line 151, in process_doc
    return str(Doc.from_comment(txt))
  File "sphinxify.py", line 145, in __str__
    return self.text + "\n".join(to_append)
AttributeError: 'Doc' object has no attribute 'text'

Suppress incorrect escaping?

  /**
   * Return this color represented as a hex string.
   *
   * @return a string of the format <tt>\#RRGGBB</tt>
   */
  std::string HexString() const;

And mypy complains about

_wpilib.pyi:2416: SyntaxWarning: invalid escape sequence '\#'
    def hexString(self) -> str:
        """
        Return this color represented as a hex string.
        
        :returns: a string of the format <tt>\#RRGGBB</tt>
        """

Enum text broken

HAL_ENUM(HAL_SimValueDirection){
    HAL_SimValueInput = 0, /**< input to user code from the simulator */
    HAL_SimValueOutput,    /**< output from user code to the simulator */
    HAL_SimValueBidir      /**< bidirectional between user code and simulator */
};

Handle inline tags that span multiple lines

Used to work, but it's broken now:

$ sphinxify
/**
 * Constructs a control-affine plant inversion model-based feedforward from
 * given model dynamics.
 *
 * If given the vector valued function as f(x, u) where x is the state
 * vector and u is the input vector, the B matrix(continuous input matrix)
 * is calculated through a NumericalJacobian. In this case f has to be
 * control-affine (of the form f(x) + Bu).
 *
 * The feedforward is calculated as
 * <strong> u_ff = B<sup>+</sup> (rDot - f(x)) </strong>, where <strong>
 * B<sup>+</sup> </strong> is the pseudoinverse of B.
 *
 * This feedforward does not account for a dynamic B matrix, B is either
 * determined or supplied when the feedforward is created and remains constant.
 *
 * For more on the underlying math, read
 * https://file.tavsys.net/control/controls-engineering-in-frc.pdf.
 */

        """Constructs a control-affine plant inversion model-based feedforward from
        given model dynamics.

        If given the vector valued function as f(x, u) where x is the state
        vector and u is the input vector, the B matrix(continuous input matrix)
        is calculated through a NumericalJacobian. In this case f has to be
        control-affine (of the form f(x) + Bu).

        The feedforward is calculated as
        ** u_ff = B<sup>+</sup> (rDot - f(x)) **, where **
        B<sup>+</sup> ** is the pseudoinverse of B.

        This feedforward does not account for a dynamic B matrix, B is either
        determined or supplied when the feedforward is created and remains constant.

        For more on the underlying math, read
        https://file.tavsys.net/control/controls-engineering-in-frc.pdf.
        """
...

docstring of wpimath._controls._controls.controller.ControlAffinePlantInversionFeedforward_1_1:9: WARNING: Inline strong start-string without end-string.
docstring of wpimath._controls._controls.controller.ControlAffinePlantInversionFeedforward_2_1:9: WARNING: Inline strong start-string without end-string.
docstring of wpimath._controls._controls.controller.ControlAffinePlantInversionFeedforward_2_2:9: WARNING: Inline strong start-string without end-string.
docstring of wpimath._controls._controls.controller.LinearPlantInversionFeedforward_1_1:3: WARNING: Inline strong start-string without end-string.
docstring of wpimath._controls._controls.controller.LinearPlantInversionFeedforward_2_1:3: WARNING: Inline strong start-string without end-string.
docstring of wpimath._controls._controls.controller.LinearPlantInversionFeedforward_2_2:3: WARNING: Inline strong start-string without end-string.

Handle in/out styled parameters

From the HAL:

/**
 * Gets the factory scaling offset constant.
 * The offset constant for the channel that was calibrated in manufacturing and
 * stored in an eeprom in the module.
 *
 * Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
 *
 * @param[in] analogPortHandle Handle to the analog port to use.
 * @param[out] status Error status variable. 0 on success.
 * @return Offset constant.
 */
int32_t HAL_GetAnalogOffset(HAL_AnalogInputHandle analogPortHandle,
                            int32_t* status);

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.