Skip to content

Merge the duplicate API documentation #300

Open
@eric-wieser

Description

@eric-wieser

Our API docs currently live in two places:

  1. in the source itself, as:

    #some_file.py
    def some_func(...):
        """ The API docs """

    for example,

    galgebra/galgebra/ga.py

    Lines 366 to 374 in 3883eca

    @staticmethod
    def build(*args, **kwargs):
    """
    Static method to instantiate geometric algebra and return geometric
    algebra, basis vectors, and grad operator as a tuple.
    """
    GA = Ga(*args, **kwargs)
    basis = list(GA.mv())
    return tuple([GA] + basis)

  2. in module-components.rst, as:

    .. function:: some_func(...)
       :no-index:
    
       The other API docs

    for example,

    .. method:: Ga.build(basis, g=None, coords=None, X=None, norm=False, debug=False)
    :noindex:
    The input parameters for ``Ga.build()`` are the same as for ``Ga()``. The difference is that in addition to returning the geometric algebra ``Ga.build()`` returns the basis vectors at the same time. Using ``Ga.build()`` in the previous example gives
    .. code:: python
    (r, th, phi) = coords = symbols('r,theta,phi', real=True)
    basis = 'e_r e_theta e_phi'
    g = [1, r**2, r**2*sin(th)**2]
    (sp3d,er,eth,ephi) = Ga.build(basis,g=g,coord=coords,norm=True)

We should merge these together, by:

  1. Manually merging the docstrings to preserve the best parts of each
  2. Removing the contents of the .. function:: directive in module-components.rst, and changing it to
    .. autofunction:: some_file.some_func
       :no-index:
    

See #301 for an example of the type of change we should be fixing this with.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions