Skip to content

Generate docs on install, nicer URLs and some caching #107

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
Open
wants to merge 11 commits into
base: master
Choose a base branch
from
Open

Generate docs on install, nicer URLs and some caching #107

wants to merge 11 commits into from
+948 −473

Conversation

line-o
Copy link
Member

@line-o line-o commented Aug 3, 2025 •
edited
Loading

This PR is built on top of #106

The client-facing URLs are changing so this might be considered a breaking change.

  • the html part is dropped from all URLs
    - /index.html -> /
    - /view.html -> /view
    - /ajax.html -> /query
    - /browse.html -> /browse

Other enhancements

  • improve XQDoc generation (add arity, parameters, annotations, module variables, ...)
    • new xqdoc structure is used to improve rendering (arity, parameters, ...)
    • this will allow future improvements
  • function signatures are rendered server-side
  • generate documentation in the finish step of the package installation
  • add cache headers to most routes that could benefit from client-side caching
  • reliably set the URL on all rendered HTML pages
  • move all page templates to /templates/pages

line-o added 5 commits August 2, 2025 11:04
@line-o
style: improve page layout and smallter tweaks
af087c1 
- footer sticks to the bottom of the window
- improve module info display
  - info icon size and alignment
  - module info boottom and right margin
  - module description foont size
- improve function info display
  - remove duplicate function name
@line-o
feat: tighten controller security, error handling
8010e62 
- rewrite scan.xql to generate.xqm
- adhere to naming conventions
- explicitly allow routes and deny evertying else
- route modules/reindex.xql moved to /regenerate
- add routes fro markdown and static resources
- call to /regenerate is a GET request
@line-o
test: adapt tests to changed app
ff5ee89 
- use new route `/exist/apps/fundocs/generate`
- do not test for removed headline in function info
- test for changed module name
@line-o
fix: links in topnavigation bar
05d22d6
@line-o
feat: generate docs on install, nicer URLs
4c6a70b 
- generate documentation in the finish step of the package installation
- add cache headers to most routes that could benefit from client-side caching
- the html part is dropped from all URLs
  - /index.html -> /
  - /view.html -> /view
  - /ajax.html -> /query
  - /browse.html -> /browse
- reliably set the URL on all rendered HTML pages
- move all page templates to /templates/pages
@line-o line-o requested review from duncdrum and a team August 3, 2025 19:01
@adamretter
Copy link
Contributor

The client-facing URLs are changing

Will the old URLs be maintained? Many people will have these bookmarked and they are likely also in printed documents including possibly the eXist-db Book.

As the W3C say - "Cool URIs don't change" - https://www.w3.org/Provider/Style/URI

line-o added 3 commits August 7, 2025 12:24
@line-o
docs: add xqdoc schema file
b990af4
@line-o
feat: generate better XQDoc
4f2aaf0 
- add arity
- add annotations
- add return with occurrence (return in comment left intact)
- add parameters with occurrence (param elements in comment left intact)
@line-o
feat: improve function signature rendering
3f74ac1
@line-o
Copy link
Member Author

line-o commented Aug 17, 2025

The breaking nature is the reason I decided to open an extra PR.

User facing URLs that could have been bookmarked or printed:

  • /exist/apps/fundocs/index.html -> /exist/apps/fundocs/
  • /exist/apps/fundocs/view.html -> /exist/apps/fundocs/view
  • /exist/apps/fundocs/browse.html -> /exist/apps/fundocs/browse
Pro Contra
There is not much to redirect unnecessary cruft on installations that cannot have been bookmarked
It's the right thing to do™ Extra effort and maintenance
Could also be handled by a proxy running in front of exist-db.org

@adamretter
Copy link
Contributor

There are a LOT more URLs than that @line-o

@line-o
Copy link
Member Author

line-o commented Aug 17, 2025

Would you be willing to share an example URL I missed?

@dizzzz
Copy link
Member

dizzzz commented Aug 17, 2025

or we "chose them very badly" :-) anyway @adamretter it really helps to provide a few concrete samples in addition to the oneliner.

@line-o
Copy link
Member Author

line-o commented Aug 18, 2025 •
edited
Loading

I just re-checked the controller and there is exactly one route matching *.html and there is exactly four existing files ending in html.
@adamretter Is it possible you mixed up documentation and function-documentation apps?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@duncdrum duncdrum Awaiting requested review from duncdrum

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@line-o @adamretter @dizzzz