Enhance documentation

[kgofron]

Comprehensive documentation enhancements and reorganization for PVXS, creating a clear separation between user guides (Markdown in docs/) and API reference (RST in documentation/). All documentation enhanced with cross-references, navigation improvements, and acknowledgments.

Changes

Reorganization

• Created docs/ directory for markdown user guides
• README.md remains in root (GitHub standard)
• RST files remain in documentation/ (Sphinx source)

Enhancements

• README.md: Added "Documentation Quick Links" section, expanded Examples with API links
• User Guides: Added "Related Documentation" sections with RST API links and cross-references
• New Files: QUICKSTART.md (tutorial), CONTRIBUTING.md (guidelines), DOCUMENTATION.md (master index), documentation/README.md (navigation guide)
• Cross-References: Enhanced links between markdown and RST docs throughout

Structure

/epics/support/pvxs/
├── README.md              # Main overview
├── docs/                  # User guides (Markdown)
│   ├── QUICKSTART.md
│   ├── INSTALLATION.md
│   ├── TROUBLESHOOTING.md
│   ├── ARCHITECTURE.md
│   ├── CONTRIBUTING.md
│   └── DOCUMENTATION.md
└── documentation/         # API reference (RST)
    ├── index.rst          # Updated with markdown references
    ├── README.md          # Navigation guide
    └── ... (RST files)

Files Changed

New: docs/QUICKSTART.md, docs/CONTRIBUTING.md, docs/DOCUMENTATION.md, documentation/README.md
Enhanced: README.md, docs/*.md files (moved and updated)
Updated: documentation/index.rst

Future

Possible: Suggested improvments to documentation directory:

1. Improve the index.rst organization
   • Better categorization in the toctree
   • Add descriptive section headers
   • No file moves required
2. Add section headers in index.rst
   • Group related docs visually
   • Improve navigation without reorganization
3. Improve cross-references
   • Better internal linking
   • Add more "see also" sections
4. Documentation comments
   • Add brief comments in index.rst explaining organization
   • Help users understand the structure

Logical layout:

documentation/
├── api/              # Core API documentation
│   ├── client.rst
│   ├── server/
│   │   ├── server.rst
│   │   ├── sharedpv.rst
│   │   └── source.rst
│   └── value/
│       ├── value.rst
│       ├── nt.rst
│       ├── ntscalar.rst
│       └── typedef.rst
├── integration/      # IOC integration
│   ├── ioc.rst
│   ├── qgroup.rst
│   └── pvalink.rst
├── guides/           # User guides
│   ├── building.rst
│   ├── cli.rst
│   ├── example.rst
│   └── netconfig.rst
└── reference/        # Reference docs
    ├── overview.rst
    ├── util.rst
    ├── details.rst
    └── releasenotes.rst

[mdavidsaver]

@kgofron I kind of see a reason for making a distinction between "user guides" vs. API reference. However, I do not like the idea of a separation which makes cross-referencing significantly more difficult. I know that sphinx+rST is not everyone's favorite. For me, it is mostly a case of not having a better way to handle generated API documentation than doxygen+breathe. I'm open to changes like reorganization of the ToC tree. Changing some files to markdown, provided that cross-references are maintained. Perhaps other reorganizing I have not thought of. And of course adding new content. However, I would like to keep all of the PVXS documentation in the sphinx environment, and published to github pages.

[mdavidsaver]

fyi. an alternative to ascii art, sphinx can process graphviz diagrams. An example from p4p.gw.

[kgofron]

@mdavidsaver : Integrate Markdown User Guides into Sphinx Documentation

Summary

This PR integrates markdown user guides into the Sphinx documentation environment and reorganizes the documentation structure into logical subdirectories, addressing PR reviewer (@mdavidsaver ) feedback to maintain all documentation in a unified Sphinx environment with improved cross-referencing.

Key Changes

1. Sphinx Configuration

• Added myst-parser extension for markdown support
• Added sphinx.ext.graphviz for diagram support
• Configured source_suffix to accept both .rst and .md files
• Updated html_static_path to include images/ directory

2. Directory Reorganization

• Created logical subdirectories: guides/, api/, reference/, examples/, images/
• Moved RST files to appropriate directories based on content type
• Moved SVG images to dedicated images/ directory
• Copied markdown files from docs/ to documentation/ subdirectories

3. Cross-Reference Updates

• Updated all markdown files to use Sphinx :doc: and :ref: syntax
• Updated RST files to reference new directory paths
• Fixed image references to use new images/ directory
• Updated ToC in index.rst with organized structure

4. Build Configuration

• Updated Makefile to handle images from images/ directory
• Added graceful fallback for missing Inkscape (copies SVGs directly)
• Updated CI workflow to install python3-myst-parser and graphviz
• Added error checking for required dependencies (Doxygen)

5. Documentation Improvements

• Removed Table of Contents sections from markdown (Sphinx generates navigation)
• Fixed table formatting for better readability
• Improved layout and spacing throughout
• Updated acknowledgments to reflect reorganization work

Benefits

• Unified Documentation: All docs in one Sphinx environment
• Better Cross-Referencing: Native Sphinx cross-references between markdown and RST
• Improved Navigation: Integrated ToC with logical grouping
• Maintainability: Clear directory structure scales better
• Asset Organization: Images in dedicated folder

Files Changed

• documentation/conf.py - Added myst-parser and graphviz support
• documentation/index.rst - Reorganized ToC structure
• documentation/Makefile - Updated image processing and dependency checks
• .github/workflows/gh-pages.yml - Added myst-parser and graphviz
• documentation/README.md - Updated to reflect new structure
• All markdown files in documentation/guides/ and documentation/examples/ - Updated cross-references
• Various RST files - Updated paths and cross-references

Testing

• Documentation builds successfully with make html
• All cross-references resolve correctly
• Markdown files render properly in Sphinx
• Images are processed and displayed correctly

Notes

• README.md in repository root remains as external reference (not part of Sphinx build)
• All references to docs/ directory have been updated to point to Sphinx documentation
• The docs/ directory can be removed after this PR is merged (files are now in documentation/guides/ and documentation/examples/)
• Graphviz support added for future diagram creation (alternative to ASCII art)