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)

[mdavidsaver]

@kgofron Could you enable github pages from action in your repository configuration? This should publish your changes as https://kgofron.github.io/pvxs

[mdavidsaver]

@kgofron Looking through these changes, it seems to me that documentation/guides/troubleshooting.md and architecture.md are fully new content. The other added markdown files appear to me to be largely repetitions of the content of the various rST files. I would like to avoid this sort of duplication. Left to me to maintain, these duplicates are all but certain to become inconsistent with time.

I do not mind having the existing content expanded. It probably should be. I have been told that my documentation is seen as too terse.

Overall, I am left to suggest that you start with smaller changes. Such a large reorganization type change is ambitious as a first contribution to any project. Having a goal in mind is good, and publishing this can help me to understand where you would like to go. However, when it comes to actually reviewing and accepting changes, it is far easier for me to have a sequence of smaller and more topical PRs. Separate content additions from reformatting, from build mechanics, from file moves. At least as separate commits, if not separate PRs.

(it is not lost on me that the above paragraph would be at home in the "Contributing" section)

[kgofron]

@mdavidsaver
I enable github pages from action in my repository configuration? This published my changes as https://kgofron.github.io/pvxs