Skip to content

Commit 3df1e17

Browse files
author
epriestley
committedJul 21, 2021
Add a side nav to Conduit API method console pages
Summary: Ref T13072. Make large Conduit doc pages a bit more navigable. This prepares for updating "harbormaster.sendmessage" to support sending messages to builds. Test Plan: Viewed various Conduit API documentation pages, clicked links. Subscribers: PHID-OPKG-gm6ozazyms6q6i22gyam Maniphest Tasks: T13072 Differential Revision: https://secure.phabricator.com/D21696
1 parent 2ff1d4b commit 3df1e17

File tree

11 files changed

+299
-115
lines changed

11 files changed

+299
-115
lines changed
 

‎resources/celerity/map.php

+3-3
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
'names' => array(
1010
'conpherence.pkg.css' => '0e3cf785',
1111
'conpherence.pkg.js' => '020aebcf',
12-
'core.pkg.css' => '0ae696de',
12+
'core.pkg.css' => '00a2e7f4',
1313
'core.pkg.js' => 'd2de90d9',
1414
'dark-console.pkg.js' => '187792c2',
1515
'differential.pkg.css' => 'ffb69e3d',
@@ -171,7 +171,7 @@
171171
'rsrc/css/phui/phui-invisible-character-view.css' => 'c694c4a4',
172172
'rsrc/css/phui/phui-left-right.css' => '68513c34',
173173
'rsrc/css/phui/phui-lightbox.css' => '4ebf22da',
174-
'rsrc/css/phui/phui-list.css' => '2f253c22',
174+
'rsrc/css/phui/phui-list.css' => '0c04affd',
175175
'rsrc/css/phui/phui-object-box.css' => 'b8d7eea0',
176176
'rsrc/css/phui/phui-pager.css' => 'd022c7ad',
177177
'rsrc/css/phui/phui-pinboard-view.css' => '1f08f5d8',
@@ -872,7 +872,7 @@
872872
'phui-invisible-character-view-css' => 'c694c4a4',
873873
'phui-left-right-css' => '68513c34',
874874
'phui-lightbox-css' => '4ebf22da',
875-
'phui-list-view-css' => '2f253c22',
875+
'phui-list-view-css' => '0c04affd',
876876
'phui-object-box-css' => 'b8d7eea0',
877877
'phui-oi-big-ui-css' => 'fa74cc35',
878878
'phui-oi-color-css' => 'b517bfa0',

‎src/__phutil_library_map__.php

+2
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,7 @@
338338
'ChatLogConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogConduitAPIMethod.php',
339339
'ChatLogQueryConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogQueryConduitAPIMethod.php',
340340
'ChatLogRecordConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogRecordConduitAPIMethod.php',
341+
'ConduitAPIDocumentationPage' => 'applications/conduit/data/ConduitAPIDocumentationPage.php',
341342
'ConduitAPIMethod' => 'applications/conduit/method/ConduitAPIMethod.php',
342343
'ConduitAPIMethodTestCase' => 'applications/conduit/method/__tests__/ConduitAPIMethodTestCase.php',
343344
'ConduitAPIRequest' => 'applications/conduit/protocol/ConduitAPIRequest.php',
@@ -6430,6 +6431,7 @@
64306431
'ChatLogConduitAPIMethod' => 'ConduitAPIMethod',
64316432
'ChatLogQueryConduitAPIMethod' => 'ChatLogConduitAPIMethod',
64326433
'ChatLogRecordConduitAPIMethod' => 'ChatLogConduitAPIMethod',
6434+
'ConduitAPIDocumentationPage' => 'Phobject',
64336435
'ConduitAPIMethod' => array(
64346436
'Phobject',
64356437
'PhabricatorPolicyInterface',

‎src/applications/conduit/controller/PhabricatorConduitConsoleController.php

+96-7
Original file line numberDiff line numberDiff line change
@@ -88,23 +88,118 @@ public function handleRequest(AphrontRequest $request) {
8888
$crumbs->addTextCrumb($method->getAPIMethodName());
8989
$crumbs->setBorder(true);
9090

91+
$documentation_pages = $method->getDocumentationPages($viewer);
92+
93+
$documentation_view = $this->newDocumentationView(
94+
$method,
95+
$documentation_pages);
96+
9197
$view = id(new PHUITwoColumnView())
9298
->setHeader($header)
9399
->setFooter(array(
100+
101+
id(new PhabricatorAnchorView())
102+
->setAnchorName('overview'),
94103
$info_box,
95-
$method->getMethodDocumentation(),
104+
105+
id(new PhabricatorAnchorView())
106+
->setAnchorName('documentation'),
107+
$documentation_view,
108+
109+
id(new PhabricatorAnchorView())
110+
->setAnchorName('call'),
96111
$form_box,
112+
113+
id(new PhabricatorAnchorView())
114+
->setAnchorName('examples'),
97115
$this->renderExampleBox($method, null),
98116
));
99117

100118
$title = $method->getAPIMethodName();
101119

120+
$nav = $this->newNavigationView($method, $documentation_pages);
121+
102122
return $this->newPage()
103123
->setTitle($title)
104124
->setCrumbs($crumbs)
125+
->setNavigation($nav)
105126
->appendChild($view);
106127
}
107128

129+
private function newDocumentationView(
130+
ConduitAPIMethod $method,
131+
array $documentation_pages) {
132+
assert_instances_of($documentation_pages, 'ConduitAPIDocumentationPage');
133+
134+
$viewer = $this->getViewer();
135+
136+
$description_properties = id(new PHUIPropertyListView());
137+
138+
$description_properties->addTextContent(
139+
new PHUIRemarkupView($viewer, $method->getMethodDescription()));
140+
141+
$description_box = id(new PHUIObjectBoxView())
142+
->setHeaderText(pht('Method Description'))
143+
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
144+
->appendChild($description_properties);
145+
146+
$view = array();
147+
$view[] = $description_box;
148+
149+
foreach ($documentation_pages as $page) {
150+
$view[] = $page->newView();
151+
}
152+
153+
return $view;
154+
}
155+
156+
private function newNavigationView(
157+
ConduitAPIMethod $method,
158+
array $documentation_pages) {
159+
assert_instances_of($documentation_pages, 'ConduitAPIDocumentationPage');
160+
161+
$console_uri = urisprintf(
162+
'/method/%s/',
163+
$method->getAPIMethodName());
164+
$console_uri = $this->getApplicationURI($console_uri);
165+
$console_uri = new PhutilURI($console_uri);
166+
167+
$nav = id(new AphrontSideNavFilterView())
168+
->setBaseURI($console_uri);
169+
170+
$nav->selectFilter(null);
171+
172+
$nav->newLink('overview')
173+
->setHref('#overview')
174+
->setName(pht('Overview'))
175+
->setIcon('fa-list');
176+
177+
$nav->newLink('documentation')
178+
->setHref('#documentation')
179+
->setName(pht('Documentation'))
180+
->setIcon('fa-book');
181+
182+
foreach ($documentation_pages as $page) {
183+
$nav->newLink($page->getAnchor())
184+
->setHref('#'.$page->getAnchor())
185+
->setName($page->getName())
186+
->setIcon($page->getIconIcon())
187+
->setIndented(true);
188+
}
189+
190+
$nav->newLink('call')
191+
->setHref('#call')
192+
->setName(pht('Call Method'))
193+
->setIcon('fa-play');
194+
195+
$nav->newLink('examples')
196+
->setHref('#examples')
197+
->setName(pht('Examples'))
198+
->setIcon('fa-folder-open-o');
199+
200+
return $nav;
201+
}
202+
108203
private function buildMethodProperties(ConduitAPIMethod $method) {
109204
$viewer = $this->getViewer();
110205

@@ -171,7 +266,6 @@ private function buildMethodProperties(ConduitAPIMethod $method) {
171266
pht('Errors'),
172267
$error_description);
173268

174-
175269
$scope = $method->getRequiredScope();
176270
switch ($scope) {
177271
case ConduitAPIMethod::SCOPE_ALWAYS:
@@ -201,11 +295,6 @@ private function buildMethodProperties(ConduitAPIMethod $method) {
201295
$oauth_description,
202296
));
203297

204-
$view->addSectionHeader(
205-
pht('Description'), PHUIPropertyListView::ICON_SUMMARY);
206-
$view->addTextContent(
207-
new PHUIRemarkupView($viewer, $method->getMethodDescription()));
208-
209298
return $view;
210299
}
211300

‎src/applications/conduit/data/ConduitAPIDocumentationPage.php

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
<?php
2+
3+
final class ConduitAPIDocumentationPage
4+
extends Phobject {
5+
6+
private $name;
7+
private $anchor;
8+
private $iconIcon;
9+
private $content = array();
10+
11+
public function setName($name) {
12+
$this->name = $name;
13+
return $this;
14+
}
15+
16+
public function getName() {
17+
return $this->name;
18+
}
19+
20+
public function setAnchor($anchor) {
21+
$this->anchor = $anchor;
22+
return $this;
23+
}
24+
25+
public function getAnchor() {
26+
return $this->anchor;
27+
}
28+
29+
public function setContent($content) {
30+
$this->content = $content;
31+
return $this;
32+
}
33+
34+
public function getContent() {
35+
return $this->content;
36+
}
37+
38+
public function setIconIcon($icon_icon) {
39+
$this->iconIcon = $icon_icon;
40+
return $this;
41+
}
42+
43+
public function getIconIcon() {
44+
return $this->iconIcon;
45+
}
46+
47+
public function newView() {
48+
$anchor_name = $this->getAnchor();
49+
$anchor_view = id(new PhabricatorAnchorView())
50+
->setAnchorName($anchor_name);
51+
52+
$content = $this->content;
53+
54+
return array(
55+
$anchor_view,
56+
$content,
57+
);
58+
}
59+
60+
61+
}

‎src/applications/conduit/method/ConduitAPIMethod.php

+27-2
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,33 @@ public function getMethodSummary() {
4040
*/
4141
abstract public function getMethodDescription();
4242

43-
public function getMethodDocumentation() {
44-
return null;
43+
final public function getDocumentationPages(PhabricatorUser $viewer) {
44+
$pages = $this->newDocumentationPages($viewer);
45+
return $pages;
46+
}
47+
48+
protected function newDocumentationPages(PhabricatorUser $viewer) {
49+
return array();
50+
}
51+
52+
final protected function newDocumentationPage(PhabricatorUser $viewer) {
53+
return id(new ConduitAPIDocumentationPage())
54+
->setIconIcon('fa-chevron-right');
55+
}
56+
57+
final protected function newDocumentationBoxPage(
58+
PhabricatorUser $viewer,
59+
$title,
60+
$content) {
61+
62+
$box_view = id(new PHUIObjectBoxView())
63+
->setHeaderText($title)
64+
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
65+
->setTable($content);
66+
67+
return $this->newDocumentationPage($viewer)
68+
->setName($title)
69+
->setContent($box_view);
4570
}
4671

4772
abstract protected function defineParamTypes();

‎src/applications/harbormaster/conduit/HarbormasterConduitAPIMethod.php

-8
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,6 @@ final public function getApplication() {
77
'PhabricatorHarbormasterApplication');
88
}
99

10-
public function getMethodStatus() {
11-
return self::METHOD_STATUS_UNSTABLE;
12-
}
13-
14-
public function getMethodStatusDescription() {
15-
return pht('All Harbormaster APIs are new and subject to change.');
16-
}
17-
1810
protected function returnArtifactList(array $artifacts) {
1911
$list = array();
2012

0 commit comments

Comments
 (0)
Failed to load comments.