diff --git a/resources/celerity/map.php b/resources/celerity/map.php --- a/resources/celerity/map.php +++ b/resources/celerity/map.php @@ -9,7 +9,7 @@ 'names' => array( 'conpherence.pkg.css' => '0e3cf785', 'conpherence.pkg.js' => '020aebcf', - 'core.pkg.css' => '0ae696de', + 'core.pkg.css' => '00a2e7f4', 'core.pkg.js' => 'd2de90d9', 'dark-console.pkg.js' => '187792c2', 'differential.pkg.css' => 'ffb69e3d', @@ -171,7 +171,7 @@ 'rsrc/css/phui/phui-invisible-character-view.css' => 'c694c4a4', 'rsrc/css/phui/phui-left-right.css' => '68513c34', 'rsrc/css/phui/phui-lightbox.css' => '4ebf22da', - 'rsrc/css/phui/phui-list.css' => '2f253c22', + 'rsrc/css/phui/phui-list.css' => '0c04affd', 'rsrc/css/phui/phui-object-box.css' => 'b8d7eea0', 'rsrc/css/phui/phui-pager.css' => 'd022c7ad', 'rsrc/css/phui/phui-pinboard-view.css' => '1f08f5d8', @@ -872,7 +872,7 @@ 'phui-invisible-character-view-css' => 'c694c4a4', 'phui-left-right-css' => '68513c34', 'phui-lightbox-css' => '4ebf22da', - 'phui-list-view-css' => '2f253c22', + 'phui-list-view-css' => '0c04affd', 'phui-object-box-css' => 'b8d7eea0', 'phui-oi-big-ui-css' => 'fa74cc35', 'phui-oi-color-css' => 'b517bfa0', diff --git a/src/__phutil_library_map__.php b/src/__phutil_library_map__.php --- a/src/__phutil_library_map__.php +++ b/src/__phutil_library_map__.php @@ -338,6 +338,7 @@ 'ChatLogConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogConduitAPIMethod.php', 'ChatLogQueryConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogQueryConduitAPIMethod.php', 'ChatLogRecordConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogRecordConduitAPIMethod.php', + 'ConduitAPIDocumentationPage' => 'applications/conduit/data/ConduitAPIDocumentationPage.php', 'ConduitAPIMethod' => 'applications/conduit/method/ConduitAPIMethod.php', 'ConduitAPIMethodTestCase' => 'applications/conduit/method/__tests__/ConduitAPIMethodTestCase.php', 'ConduitAPIRequest' => 'applications/conduit/protocol/ConduitAPIRequest.php', @@ -6430,6 +6431,7 @@ 'ChatLogConduitAPIMethod' => 'ConduitAPIMethod', 'ChatLogQueryConduitAPIMethod' => 'ChatLogConduitAPIMethod', 'ChatLogRecordConduitAPIMethod' => 'ChatLogConduitAPIMethod', + 'ConduitAPIDocumentationPage' => 'Phobject', 'ConduitAPIMethod' => array( 'Phobject', 'PhabricatorPolicyInterface', diff --git a/src/applications/conduit/controller/PhabricatorConduitConsoleController.php b/src/applications/conduit/controller/PhabricatorConduitConsoleController.php --- a/src/applications/conduit/controller/PhabricatorConduitConsoleController.php +++ b/src/applications/conduit/controller/PhabricatorConduitConsoleController.php @@ -88,23 +88,118 @@ $crumbs->addTextCrumb($method->getAPIMethodName()); $crumbs->setBorder(true); + $documentation_pages = $method->getDocumentationPages($viewer); + + $documentation_view = $this->newDocumentationView( + $method, + $documentation_pages); + $view = id(new PHUITwoColumnView()) ->setHeader($header) ->setFooter(array( + + id(new PhabricatorAnchorView()) + ->setAnchorName('overview'), $info_box, - $method->getMethodDocumentation(), + + id(new PhabricatorAnchorView()) + ->setAnchorName('documentation'), + $documentation_view, + + id(new PhabricatorAnchorView()) + ->setAnchorName('call'), $form_box, + + id(new PhabricatorAnchorView()) + ->setAnchorName('examples'), $this->renderExampleBox($method, null), )); $title = $method->getAPIMethodName(); + $nav = $this->newNavigationView($method, $documentation_pages); + return $this->newPage() ->setTitle($title) ->setCrumbs($crumbs) + ->setNavigation($nav) ->appendChild($view); } + private function newDocumentationView( + ConduitAPIMethod $method, + array $documentation_pages) { + assert_instances_of($documentation_pages, 'ConduitAPIDocumentationPage'); + + $viewer = $this->getViewer(); + + $description_properties = id(new PHUIPropertyListView()); + + $description_properties->addTextContent( + new PHUIRemarkupView($viewer, $method->getMethodDescription())); + + $description_box = id(new PHUIObjectBoxView()) + ->setHeaderText(pht('Method Description')) + ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) + ->appendChild($description_properties); + + $view = array(); + $view[] = $description_box; + + foreach ($documentation_pages as $page) { + $view[] = $page->newView(); + } + + return $view; + } + + private function newNavigationView( + ConduitAPIMethod $method, + array $documentation_pages) { + assert_instances_of($documentation_pages, 'ConduitAPIDocumentationPage'); + + $console_uri = urisprintf( + '/method/%s/', + $method->getAPIMethodName()); + $console_uri = $this->getApplicationURI($console_uri); + $console_uri = new PhutilURI($console_uri); + + $nav = id(new AphrontSideNavFilterView()) + ->setBaseURI($console_uri); + + $nav->selectFilter(null); + + $nav->newLink('overview') + ->setHref('#overview') + ->setName(pht('Overview')) + ->setIcon('fa-list'); + + $nav->newLink('documentation') + ->setHref('#documentation') + ->setName(pht('Documentation')) + ->setIcon('fa-book'); + + foreach ($documentation_pages as $page) { + $nav->newLink($page->getAnchor()) + ->setHref('#'.$page->getAnchor()) + ->setName($page->getName()) + ->setIcon($page->getIconIcon()) + ->setIndented(true); + } + + $nav->newLink('call') + ->setHref('#call') + ->setName(pht('Call Method')) + ->setIcon('fa-play'); + + $nav->newLink('examples') + ->setHref('#examples') + ->setName(pht('Examples')) + ->setIcon('fa-folder-open-o'); + + return $nav; + } + private function buildMethodProperties(ConduitAPIMethod $method) { $viewer = $this->getViewer(); @@ -171,7 +266,6 @@ pht('Errors'), $error_description); - $scope = $method->getRequiredScope(); switch ($scope) { case ConduitAPIMethod::SCOPE_ALWAYS: @@ -201,11 +295,6 @@ $oauth_description, )); - $view->addSectionHeader( - pht('Description'), PHUIPropertyListView::ICON_SUMMARY); - $view->addTextContent( - new PHUIRemarkupView($viewer, $method->getMethodDescription())); - return $view; } diff --git a/src/applications/conduit/data/ConduitAPIDocumentationPage.php b/src/applications/conduit/data/ConduitAPIDocumentationPage.php new file mode 100644 --- /dev/null +++ b/src/applications/conduit/data/ConduitAPIDocumentationPage.php @@ -0,0 +1,61 @@ +name = $name; + return $this; + } + + public function getName() { + return $this->name; + } + + public function setAnchor($anchor) { + $this->anchor = $anchor; + return $this; + } + + public function getAnchor() { + return $this->anchor; + } + + public function setContent($content) { + $this->content = $content; + return $this; + } + + public function getContent() { + return $this->content; + } + + public function setIconIcon($icon_icon) { + $this->iconIcon = $icon_icon; + return $this; + } + + public function getIconIcon() { + return $this->iconIcon; + } + + public function newView() { + $anchor_name = $this->getAnchor(); + $anchor_view = id(new PhabricatorAnchorView()) + ->setAnchorName($anchor_name); + + $content = $this->content; + + return array( + $anchor_view, + $content, + ); + } + + +} diff --git a/src/applications/conduit/method/ConduitAPIMethod.php b/src/applications/conduit/method/ConduitAPIMethod.php --- a/src/applications/conduit/method/ConduitAPIMethod.php +++ b/src/applications/conduit/method/ConduitAPIMethod.php @@ -40,8 +40,33 @@ */ abstract public function getMethodDescription(); - public function getMethodDocumentation() { - return null; + final public function getDocumentationPages(PhabricatorUser $viewer) { + $pages = $this->newDocumentationPages($viewer); + return $pages; + } + + protected function newDocumentationPages(PhabricatorUser $viewer) { + return array(); + } + + final protected function newDocumentationPage(PhabricatorUser $viewer) { + return id(new ConduitAPIDocumentationPage()) + ->setIconIcon('fa-chevron-right'); + } + + final protected function newDocumentationBoxPage( + PhabricatorUser $viewer, + $title, + $content) { + + $box_view = id(new PHUIObjectBoxView()) + ->setHeaderText($title) + ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) + ->setTable($content); + + return $this->newDocumentationPage($viewer) + ->setName($title) + ->setContent($box_view); } abstract protected function defineParamTypes(); diff --git a/src/applications/harbormaster/conduit/HarbormasterConduitAPIMethod.php b/src/applications/harbormaster/conduit/HarbormasterConduitAPIMethod.php --- a/src/applications/harbormaster/conduit/HarbormasterConduitAPIMethod.php +++ b/src/applications/harbormaster/conduit/HarbormasterConduitAPIMethod.php @@ -7,14 +7,6 @@ 'PhabricatorHarbormasterApplication'); } - public function getMethodStatus() { - return self::METHOD_STATUS_UNSTABLE; - } - - public function getMethodStatusDescription() { - return pht('All Harbormaster APIs are new and subject to change.'); - } - protected function returnArtifactList(array $artifacts) { $list = array(); diff --git a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php --- a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php +++ b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php @@ -60,7 +60,7 @@ PhabricatorEnv::getDoclink('Conduit API: Using Search Endpoints')); } - final public function getMethodDocumentation() { + final protected function newDocumentationPages(PhabricatorUser $viewer) { $viewer = $this->getViewer(); $engine = $this->newSearchEngine() @@ -70,17 +70,18 @@ $out = array(); - $out[] = $this->buildQueriesBox($engine); - $out[] = $this->buildConstraintsBox($engine); - $out[] = $this->buildOrderBox($engine, $query); - $out[] = $this->buildFieldsBox($engine); - $out[] = $this->buildAttachmentsBox($engine); - $out[] = $this->buildPagingBox($engine); + $out[] = $this->buildQueriesDocumentationPage($viewer, $engine); + $out[] = $this->buildConstraintsDocumentationPage($viewer, $engine); + $out[] = $this->buildOrderDocumentationPage($viewer, $engine, $query); + $out[] = $this->buildFieldsDocumentationPage($viewer, $engine); + $out[] = $this->buildAttachmentsDocumentationPage($viewer, $engine); + $out[] = $this->buildPagingDocumentationPage($viewer, $engine); return $out; } - private function buildQueriesBox( + private function buildQueriesDocumentationPage( + PhabricatorUser $viewer, PhabricatorApplicationSearchEngine $engine) { $viewer = $this->getViewer(); @@ -140,15 +141,18 @@ null, )); - return id(new PHUIObjectBoxView()) - ->setHeaderText(pht('Builtin and Saved Queries')) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->newRemarkupDocumentationView($info)) - ->appendChild($table); + $title = pht('Prebuilt Queries'); + $content = array( + $this->newRemarkupDocumentationView($info), + $table, + ); + + return $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor('queries'); } - private function buildConstraintsBox( + private function buildConstraintsDocumentationPage( + PhabricatorUser $viewer, PhabricatorApplicationSearchEngine $engine) { $info = pht(<<setHeaderText(pht('Custom Query Constraints')) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->newRemarkupDocumentationView($info)) - ->appendChild($table) - ->appendChild($constant_lists); + + $title = pht('Constraints'); + $content = array( + $this->newRemarkupDocumentationView($info), + $table, + $constant_lists, + ); + + return $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor('constraints') + ->setIconIcon('fa-filter'); } - private function buildOrderBox( + private function buildOrderDocumentationPage( + PhabricatorUser $viewer, PhabricatorApplicationSearchEngine $engine, $query) { @@ -388,18 +397,21 @@ 'wide', )); - - return id(new PHUIObjectBoxView()) - ->setHeaderText(pht('Result Ordering')) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->newRemarkupDocumentationView($orders_info)) - ->appendChild($orders_table) - ->appendChild($this->newRemarkupDocumentationView($columns_info)) - ->appendChild($columns_table); + $title = pht('Result Ordering'); + $content = array( + $this->newRemarkupDocumentationView($orders_info), + $orders_table, + $this->newRemarkupDocumentationView($columns_info), + $columns_table, + ); + + return $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor('ordering') + ->setIconIcon('fa-sort-numeric-asc'); } - private function buildFieldsBox( + private function buildFieldsDocumentationPage( + PhabricatorUser $viewer, PhabricatorApplicationSearchEngine $engine) { $info = pht(<<setHeaderText(pht('Object Fields')) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->newRemarkupDocumentationView($info)) - ->appendChild($table); + $title = pht('Object Fields'); + $content = array( + $this->newRemarkupDocumentationView($info), + $table, + ); + + return $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor('fields') + ->setIconIcon('fa-cube'); } - private function buildAttachmentsBox( + private function buildAttachmentsDocumentationPage( + PhabricatorUser $viewer, PhabricatorApplicationSearchEngine $engine) { $info = pht(<<setHeaderText(pht('Attachments')) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->newRemarkupDocumentationView($info)) - ->appendChild($table); + $title = pht('Attachments'); + $content = array( + $this->newRemarkupDocumentationView($info), + $table, + ); + + return $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor('attachments') + ->setIconIcon('fa-cubes'); } - private function buildPagingBox( + private function buildPagingDocumentationPage( + PhabricatorUser $viewer, PhabricatorApplicationSearchEngine $engine) { $info = pht(<<setHeaderText(pht('Paging and Limits')) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->newRemarkupDocumentationView($info)); + $title = pht('Paging and Limits'); + $content = array( + $this->newRemarkupDocumentationView($info), + ); + + return $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor('paging') + ->setIconIcon('fa-clone'); } } diff --git a/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php b/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php --- a/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php +++ b/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php @@ -13,7 +13,7 @@ 'or an entire object type.'); } - public function getMethodDocumentation() { + protected function newDocumentationPages(PhabricatorUser $viewer) { $markup = pht(<<newRemarkupDocumentationView($markup); - return id(new PHUIObjectBoxView()) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->setHeaderText(pht('Method Details')) - ->appendChild($markup); + return array( + $this->newDocumentationBoxPage($viewer, pht('Method Details'), $markup) + ->setAnchor('details'), + ); } protected function defineParamTypes() { diff --git a/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php b/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php --- a/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php +++ b/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php @@ -38,9 +38,7 @@ PhabricatorEnv::getDoclink('Conduit API: Using Edit Endpoints')); } - final public function getMethodDocumentation() { - $viewer = $this->getViewer(); - + final protected function newDocumentationPages(PhabricatorUser $viewer) { $engine = $this->newEditEngine() ->setViewer($viewer); @@ -48,16 +46,15 @@ $out = array(); - $out[] = $this->buildEditTypesBoxes($engine, $types); - - return $out; + return $this->buildEditTypesDocumentationPages($viewer, $engine, $types); } - private function buildEditTypesBoxes( + private function buildEditTypesDocumentationPages( + PhabricatorUser $viewer, PhabricatorEditEngine $engine, array $types) { - $boxes = array(); + $pages = array(); $summary_info = pht( 'This endpoint supports these types of transactions. See below for '. @@ -83,12 +80,14 @@ 'wide', )); - $boxes[] = id(new PHUIObjectBoxView()) - ->setHeaderText(pht('Transaction Types')) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->buildRemarkup($summary_info)) - ->appendChild($summary_table); + $title = pht('Transaction Summary'); + $content = array( + $this->buildRemarkup($summary_info), + $summary_table, + ); + + $pages[] = $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor('types'); foreach ($types as $type) { $section = array(); @@ -130,15 +129,18 @@ 'wide', )); - $boxes[] = id(new PHUIObjectBoxView()) - ->setHeaderText(pht('Transaction Type: %s', $type->getEditType())) - ->setCollapsed(true) - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) - ->appendChild($this->buildRemarkup($section)) - ->appendChild($type_table); + $title = $type->getEditType(); + $content = array( + $this->buildRemarkup($section), + $type_table, + ); + + $pages[] = $this->newDocumentationBoxPage($viewer, $title, $content) + ->setAnchor($type->getEditType()) + ->setIconIcon('fa-pencil'); } - return $boxes; + return $pages; } diff --git a/src/infrastructure/edges/conduit/EdgeSearchConduitAPIMethod.php b/src/infrastructure/edges/conduit/EdgeSearchConduitAPIMethod.php --- a/src/infrastructure/edges/conduit/EdgeSearchConduitAPIMethod.php +++ b/src/infrastructure/edges/conduit/EdgeSearchConduitAPIMethod.php @@ -11,9 +11,7 @@ return pht('Read edge relationships between objects.'); } - public function getMethodDocumentation() { - $viewer = $this->getViewer(); - + protected function newDocumentationPages(PhabricatorUser $viewer) { $rows = array(); foreach ($this->getConduitEdgeTypeMap() as $key => $type) { $inverse_constant = $type->getInverseEdgeConstant(); @@ -48,17 +46,11 @@ 'wide', )); - return id(new PHUIObjectBoxView()) - ->setHeaderText(pht('Edge Types')) - ->setTable($types_table); - } - - public function getMethodStatus() { - return self::METHOD_STATUS_UNSTABLE; - } - public function getMethodStatusDescription() { - return pht('This method is new and experimental.'); + return array( + $this->newDocumentationBoxPage($viewer, pht('Edge Types'), $types_table) + ->setAnchor('types'), + ); } protected function defineParamTypes() { diff --git a/webroot/rsrc/css/phui/phui-list.css b/webroot/rsrc/css/phui/phui-list.css --- a/webroot/rsrc/css/phui/phui-list.css +++ b/webroot/rsrc/css/phui/phui-list.css @@ -75,11 +75,10 @@ padding: 4px 10px; } -.phui-list-sidenav .phui-list-item-has-icon .phui-list-item-indented { - padding-left: 18px; +.phabricator-side-menu .phui-list-item-has-icon .phui-list-item-indented { + padding-left: 24px; } - .device-desktop .phui-list-sidenav .phui-list-item-href:hover { background: {$sky}; color: white;