-
Notifications
You must be signed in to change notification settings - Fork 38
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
Integrate with Discourse #29
Comments
So a user would enable the link (to Discourse) if there is a pertinent Discourse for the subject of the guide?
So have a Discourse topic for each RTD page? How would the topic be created? What Discourse category would be used?
Can you detail what this would look like? What would be the purpose of this? |
From what I understood (quick discussion with Nick at the end), we would have a link to Discourse with a unique SHIM for each RTD page. The first time any user clicks on that link, a new Discourse post is created (probably only if the user actually writes and submits something). The next time any user clicks that link, they are directed to that post and can add a comment. The same for displaying the contents. My first understanding is that if enabled (this should NOT be enabled by default!), any available comments from Discourse would be shown at the bottom of each RTD page. This would essentially give us commenting functionality (and with that community engagement) for RTD documentation. |
So, I have seen sites like this - https://blog.codinghorror.com/welcome-to-the-internet-of-compromised-things/#discourse-comments It would be interesting to set up a simple set of published docs to see what may be possible |
Thank you for reporting us your feedback! The internal ticket has been created: https://warthogs.atlassian.net/browse/DOCPR-57.
|
OK, let's liven this up a bit. I did my research, and here are my current options, in order of increasing complexity estimations:
NB: Unfortunately, there's no counterpart to create posts under topics using a link; otherwise, this would solve all our problems.
Speaking of embedding: long story short, this can be achieved, too, but I'd rather deal with the issue at hand first. Also, I'm not a fan of the idea to conflate Discourse UX with Sphinx-generated UX. |
Option (3) is the best choice imo. I would expect Discourse to do this automatically (check if a topic exists and if not create it), but if we can work around that with an extension, all good. :) I don't see a need for opening the comment box automatically - we want users to actually read existing posts in the topic before adding their own comments, which they surely wouldn't do if they were brought right to the comment box. And I think we should go for embedding the comments in the end, just to get closer to how we do documentation in Discourse, but I agree that is a second step after getting the link-up in place. |
Also, FYI @evildmp |
After trying a makeshift imitation of (3) out, I realized that it won't work nicely with private Discourse instances or whatever they are called. I'll try the API way. |
@ru-fu Here's a PoC implementation: https://canonical-workshop--120.com.readthedocs.build/en/120/ The PR (let me know if you can't access it): https://github.com/canonical/workshop/pull/120 So far, the only downside I experienced is that it significantly slows down the build (currently, each page is queried). |
In the PoC, are there any Discourse topics that exist already? I only saw pages with links to Overall, this looks good to me. It means though that if the title of a page is changed, it'll also link to a new Discourse topic. But this could make sense since it makes it easier to find the corresponding Discourse topic.
How significant is it? Like, going from 3 minutes to 6 minutes, or to 3:10? My first idea would be to add some caching so that instead of passing a function to "html-page-context", we store the result of the function in the extension and return the result from there instead of querying it more than once. But then, we are probably only querying each page once anyway - have you confirmed that? |
Would there be a way to disable this on PR builds? |
I am not sure if I understood this correctly but shouldn't this link back to an existing discourse topic where the user can leave comments? Based on Ruth's explanation above, I expected to have a discourse post created and an option provided to me for commenting on the created discourse post. However, I got an option to create a new topic. (Apologies if I understood it wrong). |
@ru-fu : there are no existing topics at this instance, although you can create one to see what happens. In short, when a topic with a given slug already exists, the extension generates a direct link to it (I looked for a 'post reply' mechanism, but it seems that'd require an API call). It's quite simple to add an override mechanism to customise topic slugs per-page (would be almost the same as with the existing The slowdown is noticeable, double time easily, which was quite unexpected for me (may depend on the connection, though). I spent some time looking for a workaround, but found nothing immediately usable. This alone will definitely need addressing before putting the extension to production use (perhaps, something akin to the @s-makin : as any other extension, it can be enabled or disabled in @keirthana : currently, we're implementing item 3 from this comment, and I still think it's a good tradeoff after trying this approach and that. Creating a dummy topic for each page in advance would cause overcrowding and confusion on Discourse. However, there is one point that definitely needs to be addressed, i.e. ensuring the page stays linked to a specific topic slug; as discussed in my response to Ruth above, it can be easily added if we're happy with the feature in general; then, it's up to the author to customise the topic slugs where needed (I don't expect topic slugs and pages to change or migrate too often). |
I updated the PR; now, it only works for pages that have the
Of course, this is now basically the same feature we have with |
I feel we need to go back to the drawing board here ... there are several issues with the current approach:
Is there a way to handle this with JavaScript? This would consider the current state, and not the state at build time. It would also not have an impact on build times (we would need to have an eye on load times, but if we see an impact there, the script could be updated to run only when someone clicks on the link). And it should also be possible to accommodate for "hardcoded" slugs in the metadata, but they wouldn't need to be required. |
@ru-fu I'm usually reluctant to resort to JS, if only for the reason some people may not have it enabled. However, your reservations are very valid, I also had similar concerns. Querying Discourse from the page itself will solve the build-time issue, obviuously, and we can still inject the hardcoded slugs if need be, but I'm not so sure about the mechanism that would reliably translate page titles into topic titles. If we're back to the drawing board, I'll sleep on this maybe, keeping in mind that the starting idea was to provide improved UX, not complicating things for everyone :) |
A brief update: while JavaScript approach is in theory feasible, it's plagued by CORS/CORB issues in practice. I'm looking for workarounds. |
@ru-fu I tried some JavaScript workarounds for CORS/CORB, but to no success, unfortunately. As long as the documentation page and the Discourse topic are under different domains, the cross-site queries will stay problematic. As a result, I suggest to either:
|
On a somewhat orthogonal note. Regarding the Discourse comments, I tried the native solution offered by Discourse (first mentioned by @evilnick earlier), but, being cross-origin in nature again, it needs to be enabled by both the Discourse admins, it seems, and generally looks a bit cumbersome to handle when you don't know the target Discourse instances in advance (i.e. not everyone will point to discourse.ubuntu.com for their discussions). It's quite possible to parse Discourse topics for recent comments to output them in the native style of the page, and I think it's the safest bet. |
I think there could be use for the slug variant you're suggesting. |
We have an "Ask a question on Discourse" link in the footer, which links to the start page of the configured Discourse.
Discourse supports adding a SHIM to a URL to identify a certain page and relate a forum post to it. We should use that in the link so that all comments for one page are combined into one post.
In addition, we should investigate if we have a way of displaying the content of the related Discourse post at the bottom of each page.
@evilnick can offer some insight.
The text was updated successfully, but these errors were encountered: