compas
compas copied to clipboard
compas-dev
Guidelines for creating API documentation?
I am wondering if we have a guideline for writing API documentation? If yes, could anyone points me to the guideline?
~~Based on my observation, I think we are using google docstring style.~~ Just want to confirm before I continue with the default sphinx_docstring style. Other than this, is there anything else that developers need to pay attention to in order to conform to the existing compas doc convention?
Great that you intend to contribute! As far as I know there is no guideline for API documentation yet. For docstrings we use the numpy docstring style.
@romanarust Thanks for your reply!
Also, I'm wondering if we can have a link to the source code in the API doc, maybe consider using sphinx.ext.viewcode? Examples can be found in pytorch's API doc here.
This will enable our users to easily navigate to the source who need to know what's going on under the hood when the API doc is not sufficient for understanding. This turns out to be the case for me when I worked with the ROS C++ API. The link to xxx line of xxx.h/xxx.cpp, e.g. see here, turns out to be very useful for me.
Also, I'm wondering if we can have a link to the source code in the API doc, maybe consider using sphinx.ext.viewcode? Examples can be found in pytorch's API doc here.
those links will be re-added as soon as the docstrings are cleaned up and consistent, which should be soon...
Other than this, is there anything else that developers need to pay attention to in order to conform to the existing compas doc convention?
we have not yet released a "dev guide", but in general we try to stick to the general Python style guides and rules as much as possible...
one thing perhaps, is that we make sure all code is accessible from the "second level". for example,
from compas.datastructures import Mesh
from compas.plotters import MeshPlotter
from compas.geometry import bounding_box
regardless of the structure of the package below that level....
i would also recommend using the cookiecutter template to create a compas package, because it will set up most of these things for you.
the current version is at https://github.com/BlockResearchGroup/cookiecutter-compas-package
