📝 Fix document

[munechika-koyo]

Issues

• Some API documentation contains typos or is incomplete.
  Fix the incorrectly spelled targetted in the document #455
• The latest sphinx_rtd_theme is incompatible with the current style settings.
  docs: Unnatural document appearance #456
• Obsolete installation guide
  docs: Update the installation guide #458
• Some RST files are not referenced because they seem stale.
• Entries at excessively deep levels are displayed in the ToC tree.

TODO list

• Corrected typos in class references and added missing classes.
  Fix the incorrectly spelled targetted in the document #455
• Introduced custom CSS for responsive table styling and image aspect ratio preservation.
• Removed previously overridden theme CSS.
• Re-configure Sphinx settings.
  docs: Unnatural document appearance #456
• Upgrade installation procedure
  docs: Update the installation guide #458
• Remove unused RST files.
• Refine toctree directives.
• Add a document about LoggingRay

Preview demo site

The modified documentation site preview is available here:
https://munechika-koyo.github.io/source/

[munechika-koyo]

Displaying version at the top of the sidebar seems deprecated since v3: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-display_version

[munechika-koyo]

BSDF-related codes were deleted (#349), but some documents still remain:

source/docs/source/demonstrations/demonstrations.rst

Lines 87 to 96 in 2487a86

	* - :ref:`Polar BRDF plots <demo_polar_brdf_plots>`
	- Producing polar plots of material BRDFs.
	- .. image:: materials/brdf_polar_plots.png
	:height: 150px
	:width: 150px
	* - :ref:`3D surface BRDF plots <demo_surface3d_brdf_plots>`
	- Producing 3D surface plots of material BRDFs.
	- .. image:: materials/brdf_surface3d_plots.png
	:height: 150px
	:width: 150px

The missing demo scripts trigger warnings during a document build like this:

WARNING: Include file '.../source/demos/reflectivity/plotting_brdfs.py' not found or reading it failed [docutils]
WARNING: Include file '.../source/demos/reflectivity/plotting_brdfs_3d.py' not found or reading it failed [docutils]

How should we handle this?

[munechika-koyo]

Additionally, there are many outdated RST files visible:

source/docs/source/api_reference/core/raysect_core_kdtree.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/architecture.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/core/energy_conservation.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/core/multiple_importance_sampling.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/core/ray_intersection_points.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/core/world_contains_point.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/anisotropic_emitters.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/diamond.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/diffuse_colours.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/emissive_colours.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/glass_bunny.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/metal_materials.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/polar_brdf_plots.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/surface3d_brdf_plots.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/surface_roughness.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/tetrahedra_mesh_emitter.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/materials/volume_inhomogeneous.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/observers/animations.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/observers/cornell_box.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/observers/cornell_box_with_camera.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/observers/mesh_observers.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/observers/metal_balls_with_lens.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/observers/optical_fibre.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/observers/orthographic_camera.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/optics/etendue_of_pinhole.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/demonstrations/optics/prism.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/quickstart_more.rst: WARNING: document isn't included in any toctree [toc.not_included]
source/docs/source/sampling.rst: WARNING: document isn't included in any toctree [toc.not_included]

[CnlPepper]

Thanks for working to update the docs. I didn't have time to go through them. Feel free to clean up any stale files, they will be in the repository history. Happy to merge this when you are ready.

[munechika-koyo]

I got it! @CnlPepper
I would try to delete all obsolete files.

Regarding BRDF plotting demo issue, I would also try to figure out how to reproduce demo scripts.

[munechika-koyo]

There are still warnings about cross-referencing classes, as shown below.
Their classes are located in different modules under raysect.core or raysect.optical.
Removing these warnings requires a precise specification like ~raysect.core.ray.Ray, not just Ray, for each type declaration in the docstring.
Because it is tedious and loses simplicity, we should keep them as warnings.

WARNING: more than one target found for cross-reference 'Ray': raysect.core.ray.Ray, raysect.optical.ray.Ray [ref.python]
WARNING: more than one target found for cross-reference 'World': raysect.core.scenegraph.world.World, raysect.optical.scenegraph.world.World [ref.python]
WARNING: more than one target found for cross-reference 'Function1D': raysect.core.math.function.float.function1d.base.Function1D, raysect.core.math.function.vector3d.function1d.base.Function1D [ref.python]
WARNING: more than one target found for cross-reference 'Function2D': raysect.core.math.function.float.function2d.base.Function2D, raysect.core.math.function.vector3d.function2d.base.Function2D [ref.python]
WARNING: more than one target found for cross-reference 'Function3D': raysect.core.math.function.float.function3d.base.Function3D, raysect.core.math.function.vector3d.function3d.base.Function3D [ref.python]

Note that it might be necessary if we need to guide users to correct API definitions.

[munechika-koyo]

There are still some warnings, except for those mentioned above (build log). However, this PR should be ready for review @CnlPepper .

The other warning:

WARNING: duplicate object description of raysect.primitive.Sphere, other instance in api_reference/primitives/geometric_primitives, use :no-index: for one of them
...

seems to be related to the fact that the Sphere class API docs are generated not only for API pages but also for the primitive page.