stashapp
Replace in-app manual with offline version of StashDocs
Describe the feature you'd like
Due to the inefficiency of maintaining multiple libraries of documentation, I propose doing away with the In-App Manual altogether, and shipping an offline version of StashDocs directly with Stash. The link to the docs can be in the same place the In-App manual exists today.
StashDocs uses "MkDocs" software, which offers an offline configuration, designed to ship documentation directly with another product. https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/
Alternatively, there are other MkDocs plugins that allow exporting documentation to formats like PDF.
Describe the benefits this would bring to existing users
With the existing setup, it's a pain to update documentation in multiple places, so updates often get delayed. Thus, the in-app manual does not align with the online StashDocs.
As @DogmaDragon recently said:
I keep kicking the can down the road since documenting the same thing in multiple places feels inefficient. The in-app manual needs a restructurization to better reflect current state of the project, but that is a major undertaking.
Is there an existing way to achieve this goal?
No
Have you searched for an existing open/closed issue?
- [x] I have searched for existing issues and none cover the core request of my proposal
Additional context
No response
We are no longer maintaining two version of the in-app manual. Since we transitioned to MkDocs from Jekyll, we are just embedding in-app manual directly from https://github.com/stashapp/stash/tree/master/ui/v2.5/src/docs/en/Manual into https://docs.stashapp.cc/in-app-manual/.
While there are some limitations due to different parsers, it mostly works well. The rest of the Stash-Docs is suplimental and I tried to cut down on duplicated information as much as possible but it probably could be refined more.
As @DogmaDragon https://github.com/stashapp/stash/issues/5298#issuecomment-3604328878:
I keep kicking the can down the road since documenting the same thing in multiple places feels inefficient. The in-app manual needs a restructurization to better reflect current state of the project, but that is a major undertaking.
I was referring to multiple sections inside the in-app manual (i.e. identify and auto tag) and the restructure of the in-app manual itself.
I haven't tested the offline mode so can't comment on that experience in general but it's not a silver bullet. It has many limitations and ultimately it would require a complete reimplementation on the Stash side since what offline plugin outputs is raw HTML not Markdown.
There is also one critical aspect that makes this no-go in my eyes. In-app manual is tied to Stash releases, while Stash-Docs is not. Adding new guides or updating some new installtion method is not version-specific most of the time, but if we integrated the whole site, then we could only update them by publishing a new release. And while MkDocs offers versioning, it doesn't work with offline plugin.
Thanks for the quick feedback. Then I'm confused on the purpose of Stash Docs "supplemental information" if it's not worth including in the in-app manual. Why shouldn't it all be included?
In the other thread, it was pointed out how the Organized flag is documented in StashDocs, but not the In-App Manual, when it should be included in both. I'm sure there are other examples of documentation missing or not in alignment between the two sources.
It makes sense to me that Stash users should have a complete, primary source of information directly available within the app. If the "supplemental" StashDocs information has value (and I assume it does, since it is referenced in discussions quite regularly) then it should be included.
There is also one critical aspect that makes this no-go in my eyes. In-app manual is tied to Stash releases, while Stash-Docs is not. Adding new guides or updating some new installtion method is not version-specific most of the time, but if we integrated the whole site, then we could only update them by publishing a new release.
This is a good point, but I don't see it as a problem. The offline docs would be out of date only to the extent its online counterpart has been updated since the latest Stash release. Stash could add a disclaimer to that effect, pointing users to the online version if they need it.