search

dipc-cc / hubbard

Python tools for mean-field Hubbard models
https://dipc-cc.github.io/hubbard/
GNU Lesser General Public License v3.0
21 stars 8 forks source link

Error trying to produce html documentation #142

Closed sofiasanz closed 11 months ago

sofiasanz commented 12 months ago

I'm trying to produce the documentation for the latest version of hubbard package and I it looks like the methods and classes information doesn't appear in the documentation. I get the following warnings and error when using sphinx.

Running Sphinx v5.0.2
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English).
making output directory... done
# Running conf_prepare.sh
~/repos/hubbard ~/repos/hubbard/docs
/home/sofia/miniconda3/envs/sphinx/bin/python3
~/repos/hubbard/docs

# Done running conf_prepare.sh

[autosummary] generating autosummary for: api.rst, examples.rst, funding.rst, index.rst, installation.rst, publications.rst
[autosummary] generating autosummary for: /home/sofia/repos/hubbard/docs/api-generated/hubbard.plot.rst, /home/sofia/repos/hubbard/docs/api-generated/hubbard.rst
loading intersphinx inventory from https://docs.python.org/dev/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/numpy/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/scipy/reference/objects.inv...
loading intersphinx inventory from https://matplotlib.org/objects.inv...
loading intersphinx inventory from https://zerothi.github.io/sisl/objects.inv...
intersphinx inventory has moved: https://matplotlib.org/objects.inv -> https://matplotlib.org/stable/objects.inv
intersphinx inventory has moved: https://docs.scipy.org/doc/numpy/objects.inv -> https://numpy.org/doc/stable/objects.inv
intersphinx inventory has moved: https://docs.scipy.org/doc/scipy/reference/objects.inv -> https://docs.scipy.org/doc/scipy/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 9 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] publications                                                                                                                                                                      
/home/sofia/repos/hubbard/docs/api.rst:19: ERROR: Error in "autosummary" directive:
unknown option: "hidden".

.. autosummary::
   :toctree: api-generated
   :hidden:

   hubbard
   hubbard.plot
/home/sofia/repos/hubbard/hubbard/__init__.py:docstring of hubbard:13: WARNING: autosummary: stub file not found 'hubbard.HubbardHamiltonian'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/__init__.py:docstring of hubbard:13: WARNING: autosummary: stub file not found 'hubbard.NEGF'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/__init__.py:docstring of hubbard:13: WARNING: autosummary: stub file not found 'hubbard.calc_n'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/__init__.py:docstring of hubbard:23: WARNING: autosummary: stub file not found 'hubbard.ncSileHubbard'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/__init__.py:docstring of hubbard:31: WARNING: autosummary: stub file not found 'hubbard.sp2'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/__init__.py:docstring of hubbard:39: WARNING: autosummary: stub file not found 'hubbard.real_space_grid'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:14: WARNING: autosummary: stub file not found 'hubbard.plot.Charge'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:14: WARNING: autosummary: stub file not found 'hubbard.plot.ChargeDifference'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:14: WARNING: autosummary: stub file not found 'hubbard.plot.SpinPolarization'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:24: WARNING: autosummary: stub file not found 'hubbard.plot.LDOS'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:24: WARNING: autosummary: stub file not found 'hubbard.plot.LDOS_from_eigenstate'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:24: WARNING: autosummary: stub file not found 'hubbard.plot.DOSmap'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:24: WARNING: autosummary: stub file not found 'hubbard.plot.Spectrum'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:35: WARNING: autosummary: stub file not found 'hubbard.plot.Wavefunction'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:43: WARNING: autosummary: stub file not found 'hubbard.plot.BondOrder'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:43: WARNING: autosummary: stub file not found 'hubbard.plot.BondHoppings'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:43: WARNING: autosummary: stub file not found 'hubbard.plot.Bonds'. Check your autosummary_generate setting.
/home/sofia/repos/hubbard/hubbard/plot/__init__.py:docstring of hubbard.plot:53: WARNING: autosummary: stub file not found 'hubbard.plot.Bandstructure'. Check your autosummary_generate setting.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] publications                                                                                                                                                                       
generating indices... genindex py-modindex done
copying notebooks ... [100%] examples/periodic.ipynb                                                                                                                                                        
writing additional pages... search done
copying images... [100%] build/doctrees/nbsphinx/examples_periodic_13_0.png                                                                                                                                 
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 20 warnings.

The HTML pages are in build/html.

I tried other versions of sphinx and I still get the same output. I'm using Python 3.10.10 and 

docutils                  0.18.1          py310h06a4308_3 
jinja2                    3.1.2           py310h06a4308_0    anaconda
sphinx                    5.0.2           py310h06a4308_0  
sphinx-autoapi            2.1.0              pyhd8ed1ab_0    conda-forge
sphinx_rtd_theme          1.2.2              pyha770c72_0    conda-forge
sphinxcontrib-applehelp   1.0.2              pyhd3eb1b0_0  
sphinxcontrib-devhelp     1.0.2              pyhd3eb1b0_0  
sphinxcontrib-dotnetdomain 0.4                        py_0    conda-forge
sphinxcontrib-golangdomain 0.2.0.dev0                 py_0    conda-forge
sphinxcontrib-htmlhelp    2.0.0              pyhd3eb1b0_0  
sphinxcontrib-jquery      4.1                pyhd8ed1ab_0    conda-forge
sphinxcontrib-jsmath      1.0.1              pyhd3eb1b0_0  
sphinxcontrib-qthelp      1.0.3              pyhd3eb1b0_0  
sphinxcontrib-serializinghtml 1.1.5              pyhd3eb1b0_0

@tfrederiksen @zerothi do you have any idea how to fix this?

zerothi commented 12 months ago

Hmm, yeah that is weird.

Indeed since this must have worked before...

The way I did things back then was not optimal. So I would probably start a bit from scratch with the autosummary and try to see if things could get working in a simpler manner.

In sisl, I have transitioned into being very explicit. It is a bit tedious, but being able to have full control is also nice considering that there are numerous utility functions that shouldn't really be exposed to end-users...

sofiasanz commented 11 months ago

Hi @zerothi, thank you for your answer :)

I found out that the file that wasn't working correctly was '_templates/autosummary/module.rst'. Is very weird, but I added a blank line before the first line in the file and now it appears to work fine... I'm very inexperienced with sphinx so I have no idea why this happened.