docs: introduce sphinx build, readthedocs, and docs workflow #81

yxlao · 2024-12-28T09:49:11Z

Summary

This PR sets up Sphinx documentation, integrates with Read the Docs, and adds a GitHub Actions workflow for automated builds.

Changes Made

Sphinx Build:
- Added Sphinx configuration (conf.py, Makefile, make.bat)
- Created documentation structure with key sections (installation, features, coordinates, contributing)
Read the Docs Integration:
- Added .readthedocs.yaml for Read the Docs configuration
- Updated README.md with links to public and admin documentation
Docs Workflow:
- Added GitHub Actions workflow (.github/workflows/docs.yml) to build docs on push and PR events
- Included [docs] extra in pyproject.toml for documentation dependencies

…endencies

…iguration

…ion locally

…tation styling and customization

…entation to improve project clarity and onboarding

…umentation files

… modules

…modules

…ts formatting refactor: remove redundant explanations in raycast.py and render.py for clarity style: fix line breaks and formatting in coordinates.rst for consistency

… conversion notes

…ush and PR events

…tra in pip install docs(README): update instructions to include `[docs]` extra and add info about Read the Docs integration

…ency

…o simplify the process

…needed

…ist to exclude Sphinx documentation artifacts

… logical flow

…dules' to 'api' for clarity and consistency

…ct' alias for consistency and brevity in documentation

…ility

…' and add 'API' section for better documentation organization

…dability and consistency

…better organization and maintainability chore(.gitignore): remove unused static and template directories from gitignore

…arch references

…flag with `make` and update paths for clarity

…ter organization and maintainability

…directory for better organization and clarity

…ry structure

…o ensure consistency

…etter organization and readability

feat(docs/conf.py): dynamically read version and git hash for release info refactor(docs/coordinates.rst): simplify section title for clarity chore(pyproject.toml): add tomli as a dependency for version parsing

…atus

…r better visibility

…y and readability

…nsistency and readability" This reverts commit c1fcd2b.

…on links

refactor(docs/conf.py): simplify path handling and use binary mode for reading pyproject.toml

… system section

… clarity and simplification

…er formatting

…t.toml to handle encoding properly

…instead of parsing pyproject.toml style(docs): replace raw HTML image tags with reStructuredText image directives for better compatibility and maintainability

… up code

…and updated toctree depth

…ings

…x.rst for better navigation and consistency

… simplify navigation

yxlao added 14 commits December 28, 2024 16:42

docs: add Sphinx documentation setup with configuration files and dep…

a622fa3

…endencies

chore: remove redundant comment in .readthedocs.yaml for cleaner conf…

7d2508b

…iguration

docs(README.md): add instructions for building and viewing documentat…

6e3c9ed

…ion locally

docs: switch from sphinx_rtd_theme to furo theme for improved documen…

1b87ad4

…tation styling and customization

docs: add contributing, coordinates, features, and installation docum…

9911fcc

…entation to improve project clarity and onboarding

style(docs): fix section underline lengths for consistency across doc…

41d0bd6

…umentation files

docs(camtools): improve docstrings for clarity and consistency across…

51ac220

… modules

docs: improve docstrings for clarity and consistency across camtools …

c18bb03

…modules

docs: update documentation build instructions and improve code commen…

94fbf78

…ts formatting refactor: remove redundant explanations in raycast.py and render.py for clarity style: fix line breaks and formatting in coordinates.rst for consistency

docs(raycast.py): clarify distance vs depth image definitions and add…

04f98a5

… conversion notes

ci: add GitHub workflow for building and deploying documentation on p…

7e4aa83

…ush and PR events

ci(docs): streamline documentation build process by using [docs] ex…

25f5db3

…tra in pip install docs(README): update instructions to include `[docs]` extra and add info about Read the Docs integration

style: reformat code for improved readability and line length consist…

a81124a

…ency

revert to original python code

d532780

yxlao changed the title ~~docs: introduce sphnix build, readthedocs, and update docs formats~~ docs: introduce sphnix build and readthedocs Dec 28, 2024

yxlao changed the title ~~docs: introduce sphnix build and readthedocs~~ docs: introduce sphnix build, readthedocs, and docs workflow Dec 28, 2024

yxlao added 3 commits December 28, 2024 18:01

chore(docs.yml): remove SPHINXOPTS from documentation build command t…

3c4b5af

…o simplify the process

revert to original python code test

cf9e01e

chore(pyproject.toml): remove black configuration as it is no longer …

a846643

…needed

yxlao changed the title ~~docs: introduce sphnix build, readthedocs, and docs workflow~~ docs: introduce sphinx build, readthedocs, and docs workflow Dec 28, 2024

yxlao added 10 commits December 28, 2024 18:09

chore(.gitignore): add docs/_static/ and docs/_templates/ to ignore l…

38a5b5d

…ist to exclude Sphinx documentation artifacts

docs(index.rst): reorder sections in the table of contents to improve…

11c90c5

… logical flow

docs(index.rst): update API documentation reference path from 'api/mo…

598ec3c

…dules' to 'api' for clarity and consistency

docs: add API reference documentation and update Sphinx configuration

2924265

docs(api.rst, conf.py): update module references from 'camtools' to '…

ec5516f

…ct' alias for consistency and brevity in documentation

docs(api.rst): add table of contents to improve navigation and readab…

9be654b

…ility

chore: remove docs/api from .gitignore as it is no longer needed

fd95627

docs(index.rst): update toctree structure, rename 'Contents' to 'Docs…

5b49be2

…' and add 'API' section for better documentation organization

docs(api.rst): restructure and align section headers for improved rea…

448c879

…dability and consistency

refactor(docs): restructure API documentation into modular files for …

91c8d12

…better organization and maintainability chore(.gitignore): remove unused static and template directories from gitignore

yxlao added 24 commits December 28, 2024 20:47

docs(index.rst): simplify indices section by removing modindex and se…

a9a55bc

…arch references

docs(README.md): simplify documentation build commands by using -C …

8a83030

…flag with `make` and update paths for clarity

refactor(docs): restructure API reference into separate files for bet…

c529c76

…ter organization and maintainability

docs: restructure API documentation by moving modules into an api sub…

512b8ab

…directory for better organization and clarity

chore(docs): add empty .gitkeep file to maintain docs/_static directo…

c9357cc

…ry structure

docs(api): fix section header formatting in API documentation files t…

02ad749

…o ensure consistency

refactor(docs): consolidate features.rst content into index.rst for b…

ca3b7ac

…etter organization and readability

docs: update configuration and improve documentation structure

170ba87

feat(docs/conf.py): dynamically read version and git hash for release info refactor(docs/coordinates.rst): simplify section title for clarity chore(pyproject.toml): add tomli as a dependency for version parsing

docs(README.md): add Read the Docs badge to indicate documentation st…

f479b73

…atus

docs(README.md): add new documentation badge with improved styling fo…

2a32721

…r better visibility

docs(README.md): standardize badge labels to lowercase for consistenc…

c1fcd2b

…y and readability

Revert "docs(README.md): standardize badge labels to lowercase for co…

bfda6c4

…nsistency and readability" This reverts commit c1fcd2b.

chore(README.md): remove duplicate Docs badge to clean up documentati…

bc89266

…on links

docs(README.md): reorder badges to improve readability and consistency

430a429

docs: update README.md with navigation links and remove redundant badges

3d02dc5

refactor(docs/conf.py): simplify path handling and use binary mode for reading pyproject.toml

docs(README.md): improve formatting and add link to camera coordinate…

5d5e8d7

… system section

docs(README.md): remove "Camera Coordinates" link from navigation for…

0d956c8

… clarity and simplification

chore: remove extra blank line in README.md for consistency and clean…

e0b81b1

…er formatting

fix(docs/conf.py): decode file content as utf-8 when reading pyprojec…

c92e094

…t.toml to handle encoding properly

refactor(docs): simplify version retrieval by using camtools package …

0e83bd9

…instead of parsing pyproject.toml style(docs): replace raw HTML image tags with reStructuredText image directives for better compatibility and maintainability

chore(docs/conf.py): remove unused import of camtools module to clean…

5f491e3

… up code

docs(api): restructure and expand API documentation with new modules …

f208cf0

…and updated toctree depth

docs: remove unused API documentation files and suppress toctree warn…

acfd0f1

…ings

docs: add repo link to README and update documentation header in inde…

c554a56

…x.rst for better navigation and consistency

yxlao marked this pull request as ready for review December 28, 2024 18:53

yxlao added 3 commits December 29, 2024 02:54

chore: rename GitHub workflow from 'Documentation' to 'Docs' for brevity

2191080

docs: add camera.rst documentation and update index.rst to reference it

c45bd1a

docs(index.rst): remove installation link from documentation index to…

5b774a8

… simplify navigation

yxlao merged commit 309a25a into main Dec 28, 2024
10 checks passed

yxlao deleted the readthedocs branch December 28, 2024 19:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: introduce sphinx build, readthedocs, and docs workflow #81

docs: introduce sphinx build, readthedocs, and docs workflow #81

yxlao commented Dec 28, 2024 •

edited

Loading

docs: introduce sphinx build, readthedocs, and docs workflow #81

docs: introduce sphinx build, readthedocs, and docs workflow #81

Conversation

yxlao commented Dec 28, 2024 • edited Loading

Summary

Changes Made

yxlao commented Dec 28, 2024 •

edited

Loading