Solve sphinx documentation problems

[DaJansenGit]

At least in some plugins the doc strings are not shown in the sphinx rendered docs: Link to cooresponding docs

[Cudok]

functions of template_mermaid.py are not shown

• this file is located in bim2sim/docs/utilities/plugindiagram

• functions like generate_plugin_structure_fig()

• solution: run sphinx-apidoc -M -o source/code utilities and add code/utilities to index.rst

[Cudok]

maybe problem refers to autodoc

• https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

[Cudok]

fresh sphinx start (from scratch)

• rename the docs folder to docs_back
• make new docs folder
• initiate sphinx

the docstring for e1_simple_project_bps_teaser.run_example_simple_building_teaser() is available

@DaJansenGit: is this a solution for the problem you described above?

[Cudok]

warning than one target found for cross-reference

• when run make html (loacally)

• ThermalZone

  • from bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_create_idf.CreateIdf.set_equipment

  • possible "links"

  • bim2sim.elements.bps_elements.ThermalZone,

  • bim2sim.plugins.PluginTEASER.bim2sim_teaser.models.ThermalZone,

  • bim2sim.utilities.visualize_spaces.ThermalZone

  • same Warning also for

  • from bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_create_idf.CreateIdf.set_lights

  • from bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_create_idf.CreateIdf.set_people

  • research:

  • strange: in the that class in other methodes spaces are defined in the same way

  • all functions who trigger this Warning the pylint returns too many arguments (these functions have args > 5 (they have 6 args)

• Window

  • from im2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_create_idf.CreateIdf.set_preprocessed_window_material_elem
  • possible "links"
  • bim2sim.elements.bps_elements.Window,
  • bim2sim.plugins.PluginTEASER.bim2sim_teaser.models.Window

• [x] understand the warning

• [x] find out howto solve

• warning not occur. when run make html the second time after make clean

  • strange, but ok

• furthermore, when replace ThermalZone by bim2sim.elements.bps_elements.ThermalZone (in Args specification) the warning is gone

  • but the linter marks bim2sim as unknown variable
  • and it looks not nice

• deactivate pylint error to many args by # pylint: disable=too-many-arguments dont remove the warning

[Cudok]

WARNING: autodoc: failed to import module 'setup' from module 'bim2sim.plugins.PluginEnergyPlus'; the module executes module level statement and it might call sys.exit().

• only the EnergyPlus Plugin has a setup.py file
• setup() is called in tests

@veronikarichter is setup() / setup.py still needed?

[Cudok]

Copyright entery

• actual 2022
• [ ] should this changed?

[Cudok]

conf.py status

• most content is included into the new conf.py (from the conf.py of the development branch)

• included extensions:

  • [x] 'myst_parser',
  • [x] 'sphinx.ext.autodoc',
  • [ ] # 'sphinx.ext.autosummary',
  • [ ] 'sphinx.ext.napoleon',
  • [ ] 'sphinx.ext.mathjax',
  • [ ] 'sphinx.ext.doctest',
  • [ ] # 'sphinx.ext.coverage',
  • [ ] 'sphinx_autodoc_typehints',
  • [x] 'sphinxcontrib.mermaid'

• further config content not included
  '# autosummary_generate = True doctest_path = [os.path.abspath('../../bim2sim/'), os.path.abspath('../utilities/plugindiagram')]

[Cudok]

adapt CI regading sphinx build

• [x] look into docs/sources/run_livereload.py >> rebuild_cmd
• [ ] Sphinx build via CI has still the problem with the missing doc strings for some methods/functions
  • tried to redo the same sphinx generation process as local done (local it works)

[Cudok]

content/sequence of concepts in Advanced User-Guide

• following items were missing in the development branch:
  • domains
  • playground
  • plugins
• just added, like thought

[DaJansenGit]

This currently works on local systems but for some reason not in the CI. We will try this again with the new pyproject.toml installation and see if the problem persists.