Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Bug]: Duplicate object warnings when building documentation #106

Open
yardasol opened this issue Jan 20, 2022 · 4 comments
Open

[Bug]: Duplicate object warnings when building documentation #106

yardasol opened this issue Jan 20, 2022 · 4 comments

Comments

@yardasol
Copy link
Contributor

yardasol commented Jan 20, 2022

Expected behavior

Following the installation instructions in the README, building the documentation should throw no errors or warnings.

Describe the bug

When building the documentation, we get the following warnings:

/home/ooblack/projects/saltproc/saltproc/separator.py:docstring of saltproc.separator.Separator.calc_rem_efficiency:1: WARNING: duplicate object description of saltproc.separator.Separator.calc_rem_efficiency, other instance in src/saltproc.separator, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/separator.py:docstring of saltproc.separator.Separator.description:1: WARNING: duplicate object description of saltproc.separator.Separator.description, other instance in src/saltproc.separator, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/separator.py:docstring of saltproc.separator.Separator.eff:1: WARNING: duplicate object description of saltproc.separator.Separator.eff, other instance in src/saltproc.separator, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/separator.py:docstring of saltproc.separator.Separator.k:1: WARNING: duplicate object description of saltproc.separator.Separator.k, other instance in src/saltproc.separator, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.calc_rem_efficiency:1: WARNING: duplicate object description of saltproc.sparger.Sparger.calc_rem_efficiency, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.description:1: WARNING: duplicate object description of saltproc.sparger.Sparger.description, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.diffusivity:1: WARNING: duplicate object description of saltproc.sparger.Sparger.diffusivity, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.eff:1: WARNING: duplicate object description of saltproc.sparger.Sparger.eff, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.eps:1: WARNING: duplicate object description of saltproc.sparger.Sparger.eps, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.exp_const:1: WARNING: duplicate object description of saltproc.sparger.Sparger.exp_const, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.gas_const:1: WARNING: duplicate object description of saltproc.sparger.Sparger.gas_const, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.h_const:1: WARNING: duplicate object description of saltproc.sparger.Sparger.h_const, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.sherwood:1: WARNING: duplicate object description of saltproc.sparger.Sparger.sherwood, other instance in src/saltproc.sparger, use :noindex: for one of them
/home/ooblack/projects/saltproc/saltproc/sparger.py:docstring of saltproc.sparger.Sparger.temp_room:1: WARNING: duplicate object description of saltproc.sparger.Sparger.temp_room, other instance in src/saltproc.sparger, use :noindex: for one of them
checking consistency... /home/ooblack/projects/saltproc/docs/src/modules.rst: WARNING: document isn't included in any toctree

To Reproduce

Steps to reproduce the behavior:

  1. Clone the repo and install the dependencies
  2. Follow the instructions to build the documentation in the readme
  3. Observe

System Specifications:

  • Software version: SaltProc v0.3.1-dev
  • Platform/OS: Ubunut 20.04 LTS

How can this issue be closed?

This issue can be closed when a PR exists that contains changes that allow the docs to be built without throwing any errors or warnings.

@yardasol
Copy link
Contributor Author

I've done some testing and discovered that these errors may have to do with PEP 257 adherence in the separator.py and sparger.py files.

These files have some attributes and functions that have multiple places where sphinx would generate documentation for them. As an example of this, consider the Sparger class:

class Sparger(Process):
     """Class evaluates gas removal efficiency in sparger (bubble generator).
 
     Attributes 
     ---------- 
     h_const : dict of str to float 
  
         ``key`` 
             Name of target isotope. 
         ``value`` 
             Henry's law constant. 
    .
    .
    .
     h_const = {'Xe': 4.3e-5, 'Kr': 2.5e-5, 'H': 2.6e-6}
    .
    .
    .

The docpage for sparger has the following:
Screenshot 2022-01-20 at 13-26-02 saltproc sparger module — Saltproc 0 3 1-dev documentation

and further down the page we have
Screenshot 2022-01-20 at 13-25-51 saltproc sparger module — Saltproc 0 3 1-dev documentation

I believe that for the attributes, this is where sphinx-build is seeing duplicates when building the documentation.
This is supported by the fact that when I delete the docstring for h_const under the Sparger class, the warning for that particular attribute having a duplicate disappears.

This is problematic because we want to follow PEP 257, but we also don't necessarily want duplicate item names in our documentation which could be confusing. @munkm any ideas?

@yardasol
Copy link
Contributor Author

sphinx-doc/sphinx#669 and sphinx-doc/sphinx#7817 may be relevant

@Fl4m3Ph03n1x
Copy link

Fl4m3Ph03n1x commented Apr 28, 2022

Do we have any updates regarding this?

@yardasol
Copy link
Contributor Author

yardasol commented Jun 7, 2022

Hi @Fl4m3Ph03n1x, since these are just warnings and don't actually have an effect on the functionality of the code, this is a low priority issue are low priority. If you feel up to the task, consider making a contribution towards resolving this issue. It would be very welcome :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants