Closed engrosamaali91 closed 1 year ago
Hi, I wonder why there is no numpydoc in the extensions? And why you put so many rst files manually instead of autogeneration? Compare to how it is done in LaPy (also templates are missing)?
Hello, I believe the sphinx-API doc in step-4 reads the .py files with docstring which I why I could see numpy docstring in the source code. Sphinx api doc command creates as many rst files as many python packages are there in the file. In brinprint we have utilis, commands, brainprint class, asymmetry, and onemore module. So sphinx api created all the corresponding rst files automatically, then its up to us which rst file we would like to add to our project. This is another method of autogeneration of rst files which I used instead of the one we used in LapY project. The reason why I used this method is that I was getting loads of warnings and errors while building html page with the LaPy method. I configured the rest as per LaPy method.
Merging #13 (d34a723) into main (e74b3a3) will not change coverage. Report is 1 commits behind head on main. The diff coverage is
n/a
.
@@ Coverage Diff @@
## main #13 +/- ##
=======================================
Coverage 27.19% 27.19%
=======================================
Files 8 8
Lines 353 353
Branches 43 43
=======================================
Hits 96 96
Misses 255 255
Partials 2 2
Flag | Coverage Δ | |
---|---|---|
unittests | 27.19% <ø> (ø) |
Flags with carried forward coverage won't be shown. Click here to find out more.
:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more
All the source files have been added to the doc folder as per LaPy documentation
The mains files are placed under doc folder
What steps I followed to generate .rst files:
In order to solve import error, I have used isort tool which automatically sorted conf.py file. Steps:
Note: BrainPrint API reference are splited into modules and brainprint classes for distinction. This can be changed as per requirements.
In commit 9170585876560ec15d80f8a5056fb8d7a1ba8883 the absolute path(local) from sphinx gallery configuration has been removed so that the document can be built on any version control systems like Git.
Please refer to line no. 234 of conf.py file.
In commit f0122ea index.rst file has been modfied as per readme.me content.
Convert README.md file which was in markdown format to index.rst file which is in restructured text.
With direct parsing of readme.md file the sphinix is unable to recognize .md format and therefore it does not generate proper headings and cover entire long text in oneline. It also does not recognize clickable pypi image in the start.
I wonder if we can find out a way to directly include the README.md rather than having a copy in rst . Currently we need to remember to edit both files if we change anything, which is not great.
black fails on conf.py
I wonder if we can find out a way to directly include the README.md rather than having a copy in rst . Currently we need to remember to edit both files if we change anything, which is not great.
True, I actually tried including README.md file directly into index.rst file but .rst file did not properly render and import .md file content and it was not properly formatted as per readme.md file. I will look more into other methods to include README.md file.
black fails on conf.py
conf.py file has been reformatted using black. 521ad6c38e62742bd7a2a81c54c11d3c05735fcb
Conf.py still fails in black. Maybe gh action uses a different version of black?
Conf.py still fails in black. Maybe gh action uses a different version of black?
Hello, The linkcode_resolve function is now identical to the one used in LaPy. I have now commented out the linkcode_resolve function on line 142 because the linkcode_resolve used in LaPy wasn't properly linking the corresponding source code on GitHub after building for BrainPrint. However, it seems that the linking is now working as expected using LaPy linkcode_resolve function.
Regarding the issue with conf.py failing in black, I am using the same version (23.7.0) of black as GitHub. Additionally, I've ensured that the conf.py adheres to the configuration defined in 'Brainprint/pyproject.toml' by running black --verbose conf.py. My local and GitHub Actions configurations are in sync." d34a72390654fbcf87c9ff3d1e661858959fc68e
Sphinix documentation
What steps I followed to generate .rst files
Git clone BrainPrint repository
Modified configuration file i.e conf.py, added relevant extension. (Some lines have been commented out such as sphinx_gallery_conf = {} as they were generating warnings and errors
Added relevant links to links.inc file
Generated rst files corresponding to python files and packages
This sphinix-apidoc creates these rst files
Then copied the brainprint.rst files details to the my toctree file i.e api-> index.rst->bp.rst
Built html files using make html
Note: The source files are not getting linked with corresponding github source code due to errors in step_2