Skip to content
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.

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

Documentation Generation Streamlining/Github Integration #2995

Open
tsole0 opened this issue Jul 29, 2024 · 0 comments
Open

Documentation Generation Streamlining/Github Integration #2995

tsole0 opened this issue Jul 29, 2024 · 0 comments
Assignees
Labels
Documentation Concerns documentation Enhancement Feature requests and/or general improvements Infrastructure GitHub, project structure, community etc

Comments

@tsole0
Copy link
Contributor

tsole0 commented Jul 29, 2024

The Problem
The current documentation generation system present in 6.0.0b2 has two looming issues:

  • Generation takes way too long and impairs user access to the feature
  • Generation is an "open loop" -- there is no way for users to submit their edited changes as a PR to SasView/SasModels

As a result of these two issues, the current implementation lacks purpose and may be confusing to users.

The Solution

Change the way documentation is generated:

  • Only generate the HTML of the page of documentation that the user edited
    • This will disable links on the page, but generation should be near-instantaneous
  • Move the functionality to re-build the entire documentation to the menu bar

Add a way for users to submit features:

  • Find a way to upload user's documentation changes to GitHub
    • Currently considering creating a git diff and submitting to GitHub via a bot account
    • Security?
  • Hide GitHub interaction from user to avoid confusion--automate the process as much as possible

The Goal

A more user-friendly documentation generator that can grow community contributions as designed

Future Expansion
Some kind of hack that will allow the user to generate only the documentation needed to properly display updated documentation without re-doing the entire documentation tree

@tsole0 tsole0 added Enhancement Feature requests and/or general improvements Documentation Concerns documentation Infrastructure GitHub, project structure, community etc labels Jul 29, 2024
@tsole0 tsole0 self-assigned this Jul 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Concerns documentation Enhancement Feature requests and/or general improvements Infrastructure GitHub, project structure, community etc
Projects
None yet
Development

No branches or pull requests

1 participant