Repository: zulip/zulip

Issue:
portico/docs: Improve OpenAPI descriptions and titles.
Followups to https://github.com/zulip/zulip/pull/11045.
- [ ] Currently we only use the first paragraph of text for the description. It would be better to concatenate the first few paragraphs, and truncate. Basically it's just using bs.find_all('p') and joining things together in a loop until it gets too long. 
One catch is that is that we probably want to stop at the first non-paragraph block so we don't cross a list or something.
- [ ] Currently, we've just tested our openAPI things with /api and /help. We should extend to the /integrations pages, and also figure out what we want to do for the top-10 major portico pages (especially /features, /why-zulip, and /for/open-source), which could benefit from a similar treatment.

To work on this I would start by skimming the code from #11045. 


Discussion:
Hello @zulip/server-misc members, this issue was labeled with the "area: misc" label, so you may want to check it out!

<!-- areaLabelAddition -->
@punchagan FYI in case you're interested in working on this.
Yeah, I will work on this. 
@zulipbot claim
The first item about using only the first paragraph was fixed in https://github.com/zulip/zulip/commit/e1f02dc6f25c58975e54d8888db6eb28e93edf7c with further improvements in other future commits.

(edit: Changed the link to point to the correct commit)
The integrations page is populated using Ajax calls, so re-using the code that populates the meta tags for the /help pages may not work very well.  I've a draft PR in #12586 that allows for adding some simple handwritten open graph tags, with just the integration name, etc being dynamic based on the URL.

For the portico pages like /features, we just render the template as a view, and again it seems quite tricky to re-use the code that populates the meta tags for /help pages. Would it be acceptable to allow adding these meta tags directly to the template, especially since there are only a handful of these page?  
I think for /integrations, just having a brief summary that it's the integration for X is probably the main thing that's useful; the actual instructions are unlikely to be that helpful without going to the page anyway?
Yeah, that's what I have in mind. :+1: 
Didn't mean to close it! Sorry! 

(The UI for GitHub's Projects is slightly confusing. I've been using it to track issues that I'm working on, and I just wanted to close the expanded view of this issue in it, but ended up closing the issue! The `x` on top goes away when I scroll down on the issue's details, and I clicked the close issue button :see_no_evil:

![image](https://user-images.githubusercontent.com/315678/59577787-ae224180-90e2-11e9-8a14-b86436979a83.png))
Hello @punchagan, you have been unassigned from this issue because you have not updated this issue or any referenced pull requests for over 14 days.

You can reclaim this issue or claim any other issue by commenting `@zulipbot claim` on that issue.

Thanks for your contributions, and hope to see you again soon!
@zulipbot Still working on it

Resolving patch:
diff --git a/zerver/views/documentation.py b/zerver/views/documentation.py
--- a/zerver/views/documentation.py
+++ b/zerver/views/documentation.py
@@ -162,6 +162,10 @@ def add_integrations_open_graph_context(context: Dict[str, Any], request: HttpRe
         context['OPEN_GRAPH_TITLE'] = 'Connect your {category} tools to Zulip'.format(category=category)
         context['OPEN_GRAPH_DESCRIPTION'] = description
 
+    elif path_name == 'integrations':
+        context['OPEN_GRAPH_TITLE'] = 'Connect the tools you use to Zulip'
+        context['OPEN_GRAPH_DESCRIPTION'] = description
+
 class IntegrationView(ApiURLView):
     template_name = 'zerver/integrations/index.html'
 


Test patch:
diff --git a/zerver/tests/test_docs.py b/zerver/tests/test_docs.py
--- a/zerver/tests/test_docs.py
+++ b/zerver/tests/test_docs.py
@@ -155,6 +155,21 @@ def test_doc_endpoints(self) -> None:
         result = self.client_get('/static/favicon.ico')
         self.assertEqual(result.status_code, 200)
 
+    def test_portico_pages_open_graph_metadata(self) -> None:
+        # Why Zulip
+        url = '/why-zulip/'
+        title = '<meta property="og:title" content="Team chat with first-class threading">'
+        description = '<meta property="og:description" content="Most team chats are overwhelming'
+        self._test(url, title, doc_html_str=True)
+        self._test(url, description, doc_html_str=True)
+
+        # Features
+        url = '/features/'
+        title = '<meta property="og:title" content="Zulip Features">'
+        description = '<meta property="og:description" content="First class threading'
+        self._test(url, title, doc_html_str=True)
+        self._test(url, description, doc_html_str=True)
+
     @slow("Tests dozens of endpoints, including all our integrations docs")
     def test_integration_doc_endpoints(self) -> None:
         self._test('/integrations/',
@@ -184,6 +199,13 @@ def test_integration_pages_open_graph_metadata(self) -> None:
         self._test(url, title, doc_html_str=True)
         self._test(url, description, doc_html_str=True)
 
+        # Test integrations page
+        url = '/integrations/'
+        title = '<meta property="og:title" content="Connect the tools you use to Zulip">'
+        description = '<meta property="og:description" content="Zulip comes with over'
+        self._test(url, title, doc_html_str=True)
+        self._test(url, description, doc_html_str=True)
+
     def test_email_integration(self) -> None:
         self._test('/integrations/doc-html/email',
                    'support+abcdefg@testserver', doc_html_str=True)