search

lifewatch / pyhydrophone

Package to make it easier to read different hydrophones' output files
GNU General Public License v3.0
9 stars 3 forks source link

errors on building the docs #1

Closed robinpaulson closed 2 years ago

robinpaulson commented 2 years ago

when i run make html, i get these errors: /home/robin/data/pyhydrophone/docs/source/data_structures.rst:14: WARNING: Title underline too short.

Hydrophone -------

WARNING: autodoc: failed to import module 'seiche' from module 'pyhydrophone'; the following exception was raised: No module named 'pyhydrophone.seiche'

Sphinx error: master file /home/robin/data/pyhydrophone/docs/source/contents.rst not found make: *** [Makefile:20: html] Error 2

robinpaulson commented 2 years ago

The first is easily fixed by adding some hyphens to the offending line in data_structures.rst.

I fixed the second by deleting the seiche section from reference.rst, but of course this doesn't fix anything, just ignores the problem (although dir(pyhydrophone) tells me there is no seiche module anyway).

The third error was fixed by changing the name of index.rst to contents.rst. I'm not sure if this is the right thing to do or not. The docs built after these changes, with this warning:

WARNING: html_static_path entry '/home/robin/data/pyhydrophone/docs/source/_static' does not exist

When I looked at the files, they were badly formatted and difficult to read, I think some new lines and css were missing. As this is python, is the formatting supposed to resemble the core python docs? Like at this site: https://docs.python.org/3/

cparcerisas commented 2 years ago

Should be solved. Can somebody check?

robinpaulson commented 2 years ago

I recloned the git repo, which got rid of the errors I reported a couple of hours ago, so I've deleted that comment. However, I am now getting this error:

Sphinx error: master file /home/robin/data/pyhydrophone/docs/source/contents.rst not found make: *** [Makefile:20: html] Error 2

robinpaulson commented 2 years ago

It works if I change the name of index.rst to contents.rst

And then complains about the lack of _static directory in source. Removing _static from L51 of conf.py solves that warning

The output again doesn't have much formatting, very little CSS - although that might be deliberate and isn't a major problem.

cparcerisas commented 2 years ago

I also had the warning (_static), but I don't get the error about contents. I don't know how to reproduce the error that you get. I get the sphinx default formatting, which is mostly b&w but quite nice I would say. Could you share a list of the sphinx installed packages?

robinpaulson commented 2 years ago

Looking again, the CSS is fine, I guess I was expecting the default python look. It's no problem

dpkg -l|grep sphinx gives:

libjs-sphinxdoc libpocketsphinx3 libsphinxbase3 python3-sphinx sphinx-common sphinxbase-utils

robinpaulson commented 2 years ago

I deleted my copy of the git repo, recloned again and ran make html. Same error about contents.rst missing, until I change the name of index.rst.

robinpaulson commented 2 years ago

Would you mind trying to reclone the repo and trying to build the docs from there?

cparcerisas commented 2 years ago

I already did, but I don't get the error.

cparcerisas commented 2 years ago

I did not get the error, but I also don't get an error changing it to contents and adding it to the config, You can clone again and check.

robinpaulson commented 2 years ago

I cloned, all is now good! Thanks, I can't work out the index/contents bug. Maybe I'm using a slightly older version of sphinx (0.8 I think)?

cparcerisas commented 2 years ago

Oh that looks like it! I am using the latest (4.3.2).

robinpaulson commented 2 years ago

Oh that looks like it! I am using the latest (4.3.2).

huh, interesting. i'll uninstall the deb and get it from pip instead. thanks for that