... | @@ -32,3 +32,9 @@ However for us the developers it will make future documentation harder as we nee |
... | @@ -32,3 +32,9 @@ However for us the developers it will make future documentation harder as we nee |
|
There is an optional parameter called :recursive: that we could add to the autossumary that in theory would travel through the entire project structure and create a stub page for everything without us having to manually insert anything. In fact, in theory, we would only need the root index.rst folder and autossumary would find all the functions nad classes in all submodules automatically. I couldnt get this to work, but if anyone wants to spend some time with it: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
|
|
There is an optional parameter called :recursive: that we could add to the autossumary that in theory would travel through the entire project structure and create a stub page for everything without us having to manually insert anything. In fact, in theory, we would only need the root index.rst folder and autossumary would find all the functions nad classes in all submodules automatically. I couldnt get this to work, but if anyone wants to spend some time with it: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
|
|
|
|
|
|
4. We should be careful with imported docstrings from overridden methods from other modules. For instance all our NN have a method called call(). this is a method that we override from tf.keras.Model and we didnt have any docstring for it. What sphinx does is it will use instead the original docs from tensorflow, which have a different styling from ours, and thus breaking the styling. I had to manually copy the docs from tensorflow and add it as a docstring with the proper formatting. Sphinx should give an error when this happens though.
|
|
4. We should be careful with imported docstrings from overridden methods from other modules. For instance all our NN have a method called call(). this is a method that we override from tf.keras.Model and we didnt have any docstring for it. What sphinx does is it will use instead the original docs from tensorflow, which have a different styling from ours, and thus breaking the styling. I had to manually copy the docs from tensorflow and add it as a docstring with the proper formatting. Sphinx should give an error when this happens though.
|
|
|
|
|
|
|
|
|
|
|
|
Usefull tips:
|
|
|
|
|
|
|
|
1. To escape special characters use \
|
|
|
|
2. To create a link to another function create use :meth:`my.function.path` and not :func: |
|
|
|
\ No newline at end of file |