Skip to content

Compile sipnet docs to gh-pages #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
dlebauer opened this issue Mar 6, 2025 · 1 comment · Fixed by #50
Closed

Compile sipnet docs to gh-pages #41

dlebauer opened this issue Mar 6, 2025 · 1 comment · Fixed by #50

Comments

@dlebauer
Copy link
Member

dlebauer commented Mar 6, 2025 •
edited
Loading

Description:

  • compile all docs (md + doxygen) into a single website
  • create GitHub action to publish these to gh-pages when changes are merged into master branch
  • optional - add make document-website (?)

In the short term, start with what we have (README, CONTRIBUTING, Doxygen, CODE_OF_CONDUCT, CHANGELOG from #33)

In the end, the documentation structure could be:

├── Home (README)
├── User Guide
│   ├── Running SIPNET
│   ├── Model Structure
│   └── Parameters and Configuration
├── Developer Guide
│   ├── Code structure
│   └── Contributing (Contributing.md)
│     └── additional details beyond scope of Contributing.md
├── API Reference (generated from Doxygen)
└── Changelog (if just a matter of adding another md file)
└── Code of Conduct

Approach

As far as frameworks, it looks like MkDocs is simple and lightweight which is consistent with the SIPNET approach. I also considered Docusaurus since it is used for the website (https://github.com/pecanproject/pecanproject.github.io), but I don't think the additional overhead is warranted for a straightforward documentation site. Both will combine md and doxygen html.

Not required, but consider whether MkDoxy will simplify Doxygen integration.
@dlebauer dlebauer mentioned this issue Mar 6, 2025
Closed
@AritraDey-Dev AritraDey-Dev mentioned this issue Mar 15, 2025
Merged
@AritraDey-Dev
Copy link
Member

@dlebauer #50 would it help?

dlebauer added a commit that referenced this issue Apr 12, 2025
@shah0108 @AritraDey-Dev @dlebauer
Build documentation using MkDocs (replaces #41) (#53)
d644a90 
* changes are made

* move changelog

* Makefile CHANGELOG and Doxyfile are modified

* required changes are made

* Update docs/Doxyfile

Co-authored-by: Aritra Dey <[email protected]>

* add rm .doxygen.stamp .mkdocs.stamp to make clean

* add .mkdocs.stamp to gitignore

* Refactor Doxygen output path and integrate src/README.md as main page
- Changed Doxygen HTML output directory to docs/api
- Updated .gitignore to ignore docs/api instead of docs/html
- Set Doxyfile OUTPUT_DIRECTORY to docs/api and HTML_OUTPUT to .
- Included src/README.md in INPUT and set it as USE_MDFILE_AS_MAINPAGE
- Modified src/README.md to serve as both GitHub README and Doxygen main page
- Updated mkdocs.yml to point API Reference to api/index.html

---------

Co-authored-by: Aritra Dey <[email protected]>
Co-authored-by: David LeBauer <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[workflow] compile sipnet docs AritraDey-Dev/sipnet
2 participants
@dlebauer @AritraDey-Dev