Random thought: asciidoclive allows editing local files, so I can open a file from my computer on it and then edit it there. It isn’t a replacement for the complete preview, but at least it’s a preview of what the page will look like without a theme etc… Can we (and how hard would it be to) extend it to fit our workflow: allow it to open files over the web, for example? Then, the “edit” option in docs could perhaps be improved to say “edit in asciidoclive”, as a sort of replacement/alternative to GitLab/Pagure editing (which doesn’t have a live preview)? It’ll open the file in asciidoclive, allow people to edit it there.
I can’t think of how we’ll abstract over the “create a copy” and “submit for review” steps, but at least folks won’t need to install anything on their systems to work on the docs?
I guess in the meantime, we mention asciidoclive in our docs so folks are aware that they can use it and not need an editor + docker/podman installed on their systems?
A more lofty, far-fetched thought: can we request GitLab (now that we’re customers?) to provide live asciidoc previews using something like this?
Mateus mentioned the idea of having a “bot” (a web service) running behind the scenes to abstract away a lot of the git complications here. It seems like a lot of work to maintain, but if people really think it will lead to improved documentation for the Fedora Project, it might be worth it.
This would be much easier for people, and beyond the issues around git, it could facilitate to free people from managing the bash scripts and make it easier to manage AsciiDoc! Indeed, a cool tool!
I see two issues we had to manage / consider:
this tool is non-bindingly / privately maintained by only one person → could we on time respond in some way if he stops maintaining / if some updates are necessary?
we need a way to put this on top of git, but given the plans mentioned in the other thread (if they prove feasible), this could indeed replace some of the work that would have to be done otherwise.
Since this is just an enhancement (“basic mode”) that makes it easier for potential contributors to aid in maintaining the documentation, it shouldn’t be a “show stopper” if it requires work at some future point to keep it running. Presumably, it would be a simple matter to disable the button that activates the live editor or to redirect it to the full GitLab interface until the problem gets fixed. The core documentation team would still be able to maintain the documentation using GitLab.
I was just thinking about this a bit more. I don’t know that much about it, but I think Antora (the tool that composes the final HTML files from the AsciiDoc sources) allows “extensions” to be hooked into the conversion pipeline. I think it should be possible to write an extension that tacks the AsciiDocLive editor onto the bottom of each documentation page in a (hidden by default) div element. All the “edit this page” button would do is unhide the div.
For the backend web service, I think it might be possible to have it do a “diff” of the revised AsciiDoc submitted from the frontend against the current site’s source AsciiDoc and email that as a merge request to GitLab.
Again, it would be a lot of work to write and maintain. But I think it might be “doable”.
I was only referring to the edit button for externals Internally, Docs uses GitLab directly, which is not related to that. But we still have to ensure that the functions for externals remain reliably working (which also includes security considerations). Also, it has to remain reliably compatible to the other technologies we use and not force us to use, e.g., legacy/vulnerable/obsolete versions of something. And someone has to take the responsibility to test and put new versions of the tool in place. I agree that this is not a big thing, and at at the worst, it might be easy to quickly change the edit button back to the GitLab interface, but we have to keep these issues in mind and consider them before just deploying something - and we have to also identify who will be responsible to ensure these tasks regularly and on time: no big deal, but to be evaluated early
Internally, Docs uses GitLab directly, which is not related to that. But we still have to ensure that the functions for externals remain reliably working (which also includes security considerations). Also, it has to remain reliably compatible to the other technologies we use and not force us to use, e.g., legacy/vulnerable/obsolete versions of something. And someone has to take the responsibility to test and put new versions of the tool in place. I agree that this is not a big thing, and at at the worst, it might be easy to quickly change the edit button back to the GitLab interface, but we have to keep these issues in mind and consider them before just deploying something - and we have to also identify who will be responsible to ensure these tasks regularly and on time: no big deal, but to be evaluated early