- {% for method in methods %}
-
- {{ block('method') }}
-
+{# BEGIN CUSTOMISATION - completely new block #}
+{% block configs %}
+
+ {% for config in configs %}
+
+ | {{ config.name|raw }} |
+ {{ hint_link(config.hint) }} |
+ {{ config.shortdesc|desc(class)|md_to_html }} |
+
+ {%- if config.class is not same as(class) -%}
+ {{ 'from %s'|trans|format(property_link(config, false, true))|raw }}
+ {%- endif -%}
+ |
+
{% endfor %}
-
-{% endblock %}
-
-{% block method %}
-
-
{% if method.class is not same as(class) %}{{ 'in %s'|trans|format(method_link(method, false, true))|raw }} {% endif %}{{ method_source_link(method) }}
- {{ block('method_signature') }}
-
-
- {{ deprecations(method) }}
-
- {% if method.shortdesc or method.longdesc %}
-
- {% if not method.shortdesc and not method.longdesc %}
-
{% trans 'No description' %}
- {% else %}
- {% if method.shortdesc -%}
-
{{ method.shortdesc|desc(class) }}
- {%- endif %}
- {% if method.longdesc -%}
-
{{ method.longdesc|desc(class) }}
- {%- endif %}
- {%- endif %}
- {% if project.config('insert_todos') == true %}
- {{ todos(method) }}
- {% endif %}
-
- {% endif %}
-
- {% if method.parameters %}
-
{% trans 'Parameters' %}
-
- {{ block('parameters') }}
- {% endif %}
-
- {% if method.hintDesc or method.hint %}
- {% trans 'Return Value' %}
-
- {{ block('return') }}
- {% endif %}
-
- {% if method.exceptions %}
- {% trans 'Exceptions' %}
-
- {{ block('exceptions') }}
- {% endif %}
-
- {% if method.tags('see') %}
- {% trans 'See also' %}
-
- {{ block('see') }}
- {% endif %}
-
-
{% endblock %}
+{# END CUSTOMISATION #}
diff --git a/conf/themes/silverstripe/doctum.js.twig b/conf/themes/silverstripe/doctum.js.twig
index eec93c2..17a4cc0 100644
--- a/conf/themes/silverstripe/doctum.js.twig
+++ b/conf/themes/silverstripe/doctum.js.twig
@@ -1,23 +1,6 @@
-{% from _self import element %}
-
-{% macro add_class_methods_index(class, prettyJsonOptions) %}
- {% if class.methods %}
- {% set from_link = class_path(class) %}
- {% for meth in class.methods %}
- {{-
- {
- type: 'Method'|trans,
- fromName: class.name,
- fromLink: from_link,
- link: method_path(meth),
- name: meth.__toString(),
- doc: meth.shortdesc|desc(class),
- }|json_encode(prettyJsonOptions)|raw
- -}},
- {% endfor %}
- {% endif %}
-{% endmacro %}
+{% include 'default/doctum.js.twig' %}
+{% verbatim -%}
(function(i,s,o,g,r,a,m){ i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
@@ -34,423 +17,4 @@ ga('linker:autoLink', [
'demo.silverstripe.org'
]);
ga('send', 'pageview');
-
-(function(root) {
-
- var bhIndex = null;
- var rootPath = '';
- var treeHtml = '{{ element(tree, project.config('default_opened_level'), 0)|replace({"'": "\\'", "\n": ''})|spaceless|raw }}';
-
- var searchTypeClasses = {
- '{{ 'Namespace'|trans|escape('js') }}': 'label-default',
- '{{ 'Class'|trans|escape('js') }}': 'label-info',
- '{{ 'Interface'|trans|escape('js') }}': 'label-primary',
- '{{ 'Trait'|trans|escape('js') }}': 'label-success',
- '{{ 'Method'|trans|escape('js') }}': 'label-danger',
- '_': 'label-warning'
- };
-
- var searchIndex = [
- {% from _self import add_class_methods_index %}
- {% set prettyJsonOptions = constant('JSON_UNESCAPED_SLASHES') b-or constant('JSON_UNESCAPED_UNICODE') %}
- {% for ns in namespaces -%}
- {{-
- {
- type: 'Namespace'|trans,
- link: namespace_path(ns),
- name: ns,
- doc: 'Namespace %s'|format(ns),
- }|json_encode(prettyJsonOptions)|raw
- -}},
- {%- endfor %}
- {% for class in interfaces -%}
- {% set interface = {
- type: 'Interface'|trans,
- link: class_path(class),
- name: class.name,
- doc: class.shortdesc|desc(class),
- } %}
- {% if class.namespace %}
- {% set interface = {
- type: interface.type,
- fromName: class.namespace,
- fromLink: namespace_path(class.namespace),
- link: interface.link,
- name: interface.name,
- doc: interface.doc,
- } %}
- {% endif %}
- {{-
- interface|json_encode(prettyJsonOptions)|raw
- -}},
- {{ add_class_methods_index(class, prettyJsonOptions) }}
- {% endfor %}
- {% for class in classes -%}
- {% set classOrTrait = {
- type: class.isTrait ? 'Trait'|trans : 'Class'|trans,
- link: class_path(class),
- name: class.name,
- doc: class.shortdesc|desc(class),
- } %}
- {% if class.namespace %}
- {% set classOrTrait = {
- type: classOrTrait.type,
- fromName: class.namespace,
- fromLink: namespace_path(class.namespace),
- link: classOrTrait.link,
- name: classOrTrait.name,
- doc: classOrTrait.doc,
- } %}
- {% endif %}
- {{-
- classOrTrait|json_encode(prettyJsonOptions)|raw
- -}},
- {{ add_class_methods_index(class, prettyJsonOptions) }}
- {% endfor %}
- {# Override this block, search_index_extra, to add custom search entries! #}
- {% block search_index_extra '' %}
- // Fix trailing commas in the index
- {}
- ];
-
- /** Tokenizes strings by namespaces and functions */
- function tokenizer(term) {
- if (!term) {
- return [];
- }
-
- var tokens = [term];
- var meth = term.indexOf('::');
-
- // Split tokens into methods if "::" is found.
- if (meth > -1) {
- tokens.push(term.substr(meth + 2));
- term = term.substr(0, meth - 2);
- }
-
- // Split by namespace or fake namespace.
- if (term.indexOf('\\') > -1) {
- tokens = tokens.concat(term.split('\\'));
- } else if (term.indexOf('_') > 0) {
- tokens = tokens.concat(term.split('_'));
- }
-
- // Merge in splitting the string by case and return
- tokens = tokens.concat(term.match(/(([A-Z]?[^A-Z]*)|([a-z]?[^a-z]*))/g).slice(0,-1));
-
- return tokens;
- };
-
- root.Doctum = {
- /**
- * Cleans the provided term. If no term is provided, then one is
- * grabbed from the query string "search" parameter.
- */
- cleanSearchTerm: function(term) {
- // Grab from the query string
- if (typeof term === 'undefined') {
- var name = 'search';
- var regex = new RegExp("[\\?&]" + name + "=([^&#]*)");
- var results = regex.exec(location.search);
- if (results === null) {
- return null;
- }
- term = decodeURIComponent(results[1].replace(/\+/g, " "));
- }
-
- return term.replace(/<(?:.|\n)*?>/gm, '');
- },
-
- /** Searches through the index for a given term */
-search: function(term) {
- var searchField = $('#search-form .tt-input');
- var rankByType = function (type) {
- switch (type) {
- case 'Class':
- case 'Trait':
- case 'Interface':
- return 1;
- case 'Namespace':
- return 2;
- case 'Method':
- default:
- return 3;
- }
- }
- // Create a new search index if needed
- if (!bhIndex) {
- bhIndex = new Bloodhound({
- limit: 500,
- local: searchIndex,
- datumTokenizer: function (d) {
- return tokenizer(d.name);
- },
- queryTokenizer: Bloodhound.tokenizers.whitespace,
- sorter: function(a, b) {
- // not sure how to get the search term in a nicer way than this
- var term = searchField.val() || Doctum.cleanSearchTerm();
-
- var lowerTerm = term.toLowerCase();
-
- var matcher = function (a, b, aObj, bObj, ignoreEnds) {
-
- // always prioritise by type - this stops methods polluting the results
- var aPriority = rankByType(aObj.type);
- var bPriority = rankByType(bObj.type);
-
- if (aPriority > bPriority) {
- return 1;
- }
- if (aPriority < bPriority) {
- return -1
- }
-
- // normalise terms
- a = a.toLowerCase();
- b = b.toLowerCase();
-
- if (a !== b) {
- // prefer exact match
- if (lowerTerm == a) {
- return -1;
- }
- if (lowerTerm == b) {
- return 1;
- }
- }
-
- // if they match equally well, rank on type
- if (a == b || (!ignoreEnds && (a.endsWith(lowerTerm) && b.endsWith(lowerTerm)) || (a.startsWith(lowerTerm) && b.startsWith(lowerTerm)))) {
-
- // if they match on type, they should sort alphabetically
- if (aPriority == bPriority) {
- // alphabetically
- if (a == b) {
- return 0;
- }
- if (a > b) {
- return 1;
- } else {
- return -1;
- }
- }
- // sort by type
- if (aPriority > bPriority) {
- return 1
- } else {
- return -1;
- }
- }
-
- // allow skipping of matching begins and ends of stings (useful when sorting the FQNS)
- if (ignoreEnds) {
- return null;
- }
-
- // if strings start with the search term, prefer them
- if (a.startsWith(lowerTerm)) {
- return -1;
- }
-
- if (b.startsWith(lowerTerm)) {
- return 1;
- }
-
- // if strings end with the search term, prefer them
- if (a.endsWith(lowerTerm)) {
- return -1;
- }
-
- if (b.endsWith(lowerTerm)) {
- return 1;
- }
- }
-
- var match = null;
-
- // try to match against the FQNS
- match = matcher(a.name, b.name, a, b, true);
- if (typeof match === 'number') {
- return match;
- }
-
- var splitter = function(item) {
- var parts = item.name.split('\\');
- if (item.type == 'Method') {
- var methodParts = parts.pop().split('::');
- parts = parts.concat(methodParts);
- }
- return parts;
- }
-
- //split at namespace separator
- var aParts = splitter(a);
- var bParts = splitter(b);
-
- // go through each part of the FQNS and compare from the end
- do {
- var aPart = aParts.pop();
- var bPart = bParts.pop();
-
- match = matcher(aPart, bPart, a, b);
- if (typeof match === 'number') {
- return match;
- }
-
- } while (aParts.length && bParts.length);
-
- return 0;
- }
- });
- bhIndex.initialize();
- }
-
- results = [];
- bhIndex.get(term, function(matches) {
- results = matches;
- });
-
- if (!rootPath) {
- return results;
- }
-
- // Fix the element links based on the current page depth.
- return $.map(results, function(ele) {
- if (ele.link.indexOf('..') > -1) {
- return ele;
- }
- ele.link = rootPath + ele.link;
- if (ele.fromLink) {
- ele.fromLink = rootPath + ele.fromLink;
- }
- return ele;
- });
- },
-
- /** Get a search class for a specific type */
- getSearchClass: function(type) {
- return searchTypeClasses[type] || searchTypeClasses['_'];
- },
-
- /** Add the left-nav tree to the site */
- injectApiTree: function(ele) {
- ele.html(treeHtml);
- }
- };
-
- $(function() {
- // Modify the HTML to work correctly based on the current depth
- rootPath = $('body').attr('data-root-path');
- treeHtml = treeHtml.replace(/href="/g, 'href="' + rootPath);
- Doctum.injectApiTree($('#api-tree'));
- });
-
- return root.Doctum;
-})(window);
-
-$(function() {
-
- {% if project.versions|length > 1 %}
- // Enable the version switcher
- $('#version-switcher').on('change', function() {
- window.location = $(this).val()
- });
- var versionSwitcher = document.getElementById('version-switcher');
- if (versionSwitcher) {
- var versionToSelect = document.evaluate(
- '//option[@data-version="{{ project.version|escape('js') }}"]',
- versionSwitcher,
- null,
- XPathResult.FIRST_ORDERED_NODE_TYPE,
- null
- ).singleNodeValue;
-
- if (versionToSelect && typeof versionToSelect.selected === 'boolean') {
- versionToSelect.selected = true;
- }
- }
- {% endif %}
-
- {% block treejs %}
-
- // Toggle left-nav divs on click
- $('#api-tree .hd span').on('click', function() {
- $(this).parent().parent().toggleClass('opened');
- });
-
- // Expand the parent namespaces of the current page.
- var expected = $('body').attr('data-name');
-
- if (expected) {
- // Open the currently selected node and its parents.
- var container = $('#api-tree');
- var node = $('#api-tree li[data-name="' + expected + '"]');
- // Node might not be found when simulating namespaces
- if (node.length > 0) {
- node.addClass('active').addClass('opened');
- node.parents('li').addClass('opened');
- var scrollPos = node.offset().top - container.offset().top + container.scrollTop();
- // Position the item nearer to the top of the screen.
- scrollPos -= 200;
- container.scrollTop(scrollPos);
- }
- }
-
- {% endblock %}
-
- {% verbatim %}
- var form = $('#search-form .typeahead');
- form.typeahead({
- hint: true,
- highlight: true,
- minLength: 1
- }, {
- name: 'search',
- displayKey: 'name',
- source: function (q, cb) {
- cb(Doctum.search(q));
- }
- });
-
- // The selection is direct-linked when the user selects a suggestion.
- form.on('typeahead:selected', function(e, suggestion) {
- window.location = suggestion.link;
- });
-
- // The form is submitted when the user hits enter.
- form.keypress(function (e) {
- if (e.which == 13) {
- $('#search-form').submit();
- return true;
- }
- });
-
- {% endverbatim %}
-});
-
-
-{% macro element(tree, opened, depth) %}
- {% from _self import element %}
-
-
-{% endmacro %}
+{% endverbatim -%}
diff --git a/src/Console/CheckoutCommand.php b/src/Console/CheckoutCommand.php
index fd5b003..3304168 100644
--- a/src/Console/CheckoutCommand.php
+++ b/src/Console/CheckoutCommand.php
@@ -27,7 +27,7 @@ class CheckoutCommand extends Command
'/-theme$/',
];
- public function run(InputInterface $input, OutputInterface $output)
+ public function execute(InputInterface $input, OutputInterface $output)
{
$config = Config::getConfig();
@@ -63,6 +63,8 @@ public function run(InputInterface $input, OutputInterface $output)
}
$this->writeMapToDisk($versionMap, $config, $output);
+
+ return self::SUCCESS;
}
/**
diff --git a/src/Data/ApiJsonStore.php b/src/Data/ApiJsonStore.php
index 4eec29f..e0084a3 100644
--- a/src/Data/ApiJsonStore.php
+++ b/src/Data/ApiJsonStore.php
@@ -4,6 +4,7 @@
use Doctum\Project;
use Doctum\Store\JsonStore;
+use RuntimeException;
/**
* Adjust json store to not fail on branches with fewer classes than others
@@ -12,9 +13,19 @@ class ApiJsonStore extends JsonStore
{
public function removeClass(Project $project, $name)
{
- $path = $this->getFilename($project, $name);
- if (file_exists($path)) {
- unlink($path);
+ try {
+ parent::removeClass($project, $name);
+ } catch (RuntimeException $e) {
+ // no-op - let the site finish building.
+ }
+ }
+
+ public function removeFunction(Project $project, string $name): void
+ {
+ try {
+ parent::removeFunction($project, $name);
+ } catch (RuntimeException $e) {
+ // no-op - let the site finish building.
}
}
}
diff --git a/src/Inspections/RecipeFinder.php b/src/Inspections/RecipeFinder.php
index fa0dce8..3ff0f46 100644
--- a/src/Inspections/RecipeFinder.php
+++ b/src/Inspections/RecipeFinder.php
@@ -2,6 +2,7 @@
namespace SilverStripe\ApiDocs\Inspections;
+use Iterator;
use ReflectionProperty;
use Symfony\Component\Finder\Finder;
@@ -18,7 +19,7 @@ public function __construct(RecipeVersionCollection $collection)
$this->collection = $collection;
}
- public function getIterator()
+ public function getIterator(): Iterator
{
// Clear all dirs
$this->resetDirs();
diff --git a/src/Parser/Filter/SilverStripeFilter.php b/src/Parser/Filter/SilverStripeFilter.php
index 1defb0f..f7bcea1 100644
--- a/src/Parser/Filter/SilverStripeFilter.php
+++ b/src/Parser/Filter/SilverStripeFilter.php
@@ -2,12 +2,12 @@
namespace SilverStripe\ApiDocs\Parser\Filter;
-use Doctum\Parser\Filter\PublicFilter;
+use Doctum\Parser\Filter\DefaultFilter;
use Doctum\Reflection\ClassReflection;
use Doctum\Reflection\MethodReflection;
use Doctum\Reflection\PropertyReflection;
-class SilverStripeFilter extends PublicFilter
+class SilverStripeFilter extends DefaultFilter
{
public function acceptClass(ClassReflection $class)
{
@@ -21,8 +21,7 @@ public function acceptMethod(MethodReflection $method)
public function acceptProperty(PropertyReflection $property)
{
- // if there's a config tag, then we want to document it
- return !$property->getTags('internal') &&
- ($property->getTags('config') || parent::acceptProperty($property));
+ // Explicitly allow private static properties
+ return !$property->getTags('internal') && ($property->isStatic() || parent::acceptProperty($property));
}
}
diff --git a/src/Reflection/SilverStripeClassReflection.php b/src/Reflection/SilverStripeClassReflection.php
index cc330a0..4d269f9 100644
--- a/src/Reflection/SilverStripeClassReflection.php
+++ b/src/Reflection/SilverStripeClassReflection.php
@@ -7,18 +7,39 @@
class SilverStripeClassReflection extends ClassReflection
{
-
/** @var array
*/
protected $configs = [];
public function addConfig(PropertyReflection $property): void
{
$this->configs[$property->getName()] = $property;
- $property->setClass($this);
}
- public function getConfigs(): array
+ public function getConfigs($deep = false): array
{
+ if (empty($this->configs) && $this->hasTrait('SilverStripe\Core\Config\Configurable')) {
+ foreach ($this->getProperties($deep) as $property) {
+ if ($this->propertyIsConfig($property)) {
+ $this->addConfig($property);
+ }
+ }
+ }
return $this->configs;
}
+
+ public function propertyIsConfig(PropertyReflection $property): bool
+ {
+ return !$property->isInternal() && $property->isStatic() && $property->isPrivate();
+ }
+
+ private function hasTrait(string $traitName): bool
+ {
+ $traits = $this->getTraits(true);
+ foreach ($traits as $trait) {
+ if ($trait->getName() === $traitName) {
+ return true;
+ }
+ }
+ return false;
+ }
}