[Bug]: Duplicate object warnings when building documentation

[yardasol]

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]

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:

and further down the page we have

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]

https://github.com/sphinx-doc/sphinx/issues/669 and https://github.com/sphinx-doc/sphinx/issues/7817 may be relevant

[Fl4m3Ph03n1x]

Do we have any updates regarding this?

[yardasol]

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 :)