silverstripe / api.silverstripe.org Goto Github PK

We use it to document our config, so not mentioning these in API docs is very limiting. Example: http://api.silverstripe.org/4/SilverStripe/Assets/File.html doesn't contain allowed_extensions.

At bottom of pages:

Replace with HTML.

Link goes to https://ssapi-uat.sites.silverstripe.com/3/.html which doesn't work

From @SpiritLevel

The parsing of [api:Director] style short codes seems to be generating the correct query:
api.silverstripe.org/search/lookup/?q=Director&version=3&module=framework
The problem is that the api site no longer processes such queries. These queries used to work :(

silverstripe/silverstripe-framework#11066 added generic typehints in a bunch of places.

Validate these are rendering in a helpful way in the API docs. If necessary, fix the way these are being rendered.

After the migration to sami there was an issue adding canonical urls;

This is the code I was using

<link rel="canonical"
    href="{{ project.config('base_url')|replace({'%version%': project.version.name}) }}/{{ uri }}"
/>

Since documents are cached between versions (e.g. 4, master, 3) it's not possible to render version-specific canonical urls, since it pollutes other versions.

I've tracked the code which pollutes the cache to Project::renderVersion

if ($previous && !$this->renderer->isRendered($this)) {
    $this->seedCache($previous, $this->getBuildDir());
}

However, removing this line causes so much extra work the task runs out of memory and crashes, so it needs to be left in for now.

When you're looking at some API, and then swap versions, it kicks you back up to the namespaces page instead of showing you the new version of the API you were looking at.

e.g.

1. go to https://api.silverstripe.org/4/SilverStripe/CMS/Model/SiteTree.html
2. swap to "5.x"
3. You should be taken to https://api.silverstripe.org/5/SilverStripe/CMS/Model/SiteTree.html but instead you're taken to https://api.silverstripe.org/5/index.html

PRs

• #112

In preparation for release of SilverStripe 4 a major upgrade of api.silverstripe.org will be necessary. Given the range of options it's likely we'll move away from ApiGen to another backend, shifting the hosting to SilverStripe platform, and upgrade to PHP7.

Tasks:

• Choose a new API generator. Candidates include (but not limited to):
  • https://www.phpdoc.org/
  • https://github.com/FriendsOfPHP/Sami
  • http://phpdox.de/
• Shift hosting to platform, running PHP 7.
• Upgrade base project to use the new platform
• Generate docs for 3, 4, and 5 (master)
• Deploy

Load a lot of images into the assets into a subfolder/ subfolders
In the Files interface select the folder(s) and "delete" them
Wait. Wait....

I would extensively test this but I have been waiting 40 minutes for the process to finish.

From silverstripe/silverstripe-framework#7625

Method summary & method elaboration shows no major differences (might as well link me to the source code like the old doc)
Too much repeating information in one page.

@tractorcow said: "Maybe regarding 6. / 8. we could restructure the summary / elaboration... clicking the summary "expands" the elaboration directly below, similar to an accordion. @clarkepaul what do you think about this?"

The API doc is broken on CMS4.

https://api.silverstripe.org/4/index.html

SS4 uses these new modules, they need to be added to the API source, plus other core dependencies

This was a feature we used a lot on the old version, we always found browsing methods on a class a little easier.

Behold the results:
http://api.silverstripe.org/4/search.html?search=DataObject
Please also note the non-functional auto-completer in the top-left
And that the adblocker is disabled (top right)

Loading the site on index.php sees the auto-completer begin functioning again

Search page is reached by submitting the auto-completer input
type "DataObject" then press enter; although auto-completions exist and are valid, the fact there are more than one matches means it goes to the results page, which then shows no results.

I noticed that api is missing docs for 3.4. The needed changes seem fairly obvious and are in:

https://github.com/silverstripe/api.silverstripe.org/blob/master/makedoc.sh
https://github.com/silverstripe/api.silverstripe.org/blob/master/htdocs/.htaccess
https://github.com/silverstripe/api.silverstripe.org/blob/master/conf/apigen/templates/%40layout.latte

Happy to submit PR; I just wanted to first check with those in the know. :)

Affected Version

SS 4.3

Description

DateTime.Format in a template used to work fine, now gives broken results like 16/33/2018
The date is correctly stored in the database and is correctly retrieved if dumped in PHP before used in template.

Steps to Reproduce

Give the template a datetime from the database and call Format on it in the template code.

The documentation on api.silverstripe.org gives nothing but the format string as an explanation for the format parameter (in fact not even that, it's just described as that in a side sentence for the function itself).
Obviously proper format strings that are well known and which people are used to don't work.
One has to Google for the issue (after figuring out the display is what's broken), then find a Stackoverflow Question that then links some ominous changelog which contains some remote mention of it in one of its thousands of lines... Then you have to Google the format to actually find any helpful information.
That's like 10 steps, where one should suffice. Took me like an hour to find the necessary information to change a few characters in the template...

This is ridiculous BS, really pissed off....

Docs are out of date for new SAMI backend

This thing is still running on PHP 7.3!

Update it to PHP 8.1. This is hosted in silverstripe cloud so we know the hosting can support it.

Prs

NOTE: Once this has been merged, either deploy it to ssapi2 or reassign to Guy to do that.

• #108

SilverStripe 4.3 ships with this module by default, so we should add it to the API docs.

There is now a bug with the MASTER docs where an error:

The TokenReflection library threw an exception while parsing the file

Occurs when parsing a file using the MyClass::class syntax - which is all over SS4. See ApiGen/ApiGen#680 for the issue. There are two ways to solve this: either use the fork of the token reflection: ApiGen/ApiGen#680 (comment) or upgrade to the unstable 5.0.0-rc5 (and PHP7.1).

http://api.silverstripe.org/4/SilverStripe/Forms/FieldList.html#method_dataFieldNames

There is no method dataFieldNames at vendor/silverstripe/framework/src/Forms/FieldList.php
But there is API docs for it
I am using SS 4.0 CMS 4.0

Tests are broken, need updating with new search engine rules

See http://api.silverstripe.org/4/SilverStripe/Forms/DropdownField.html

The phpdoc for the DropdownField class contains the line Dropdown field, created from a <select> tag. an actual tag is rendered, throwing off the whole page. This can be worked around by using <select> instead - which means that either:

a) the content needs to be sanitised before rendered - see https://github.com/FriendsOfPHP/Sami/issues/261
b) we need to check all our classes for tags and update/remove them accordingly

https://docs.silverstripe.org/en/4/developer_guides/extending/extensions/

Link for DataExtension at foot of page links to:

http://api.silverstripe.org/search/lookup/?q=DataExtension&version=4&module=framework&_ga=1.176688039.308834275.1455201581

Which errors with:

Not Found

The requested URL /4/class-DataExtension.html was not found on this server.

E.g. https://api.silverstripe.org/4/SilverStripe/Forms/MultiSelectField.html. SilverStripe\Forms\MultiSelectField is an abstract class, but there’s nothing to indicate that on the API page for it

From @tractorcow on silverstripe/silverstripe-framework#7625

It's been raised that we might need a "hide inherited members" feature, maybe on by default, so that you can limit the page to only members at the current inheritance. That should address 2.

Tracks upstream issue https://github.com/FriendsOfPHP/Sami/issues/62

Pull request with fix is FriendsOfPHP/Sami#311

DropdownField has the protected function getFieldOption() as shown here: https://github.com/silverstripe/silverstripe-framework/blob/4/src/Forms/DropdownField.php#L97, however this doesn't show up on the API docs: https://api.silverstripe.org/4/SilverStripe/Forms/DropdownField.html

In fact, no protected functions are showing up, I suspect that means there's a bug there.

Functions should also surface their visibility in these docs.

PRs

• #108

In Chrome on MacOS High Sierra.

The dropdown doesn't drop down, however the inspector shows the right options are in the dropdown.

The SilverStripe API website is offline since a week.

Recently we updated the SilverStripe.com and SilverStripe.org search from Google Custom Search to Swiftype. The CSS now references a Swiftype specific search input and the JS for Google has been replaced with Swiftype JS. This has broken the GlobalNav search (the search bar that is displayed when you click the search icon in the nav in the top right).

I believe the fix may be to replace the following lines:
https://github.com/silverstripe/api.silverstripe.org/blob/master/conf/themes/silverstripe/layout/layout.twig#L48-L51

With:

        <div id="swiftype-search">
            <div class="swiftype-control-searchbox-only" dir="ltr">
                <form class="swiftype-search-box" accept-charset="utf-8">
                    <table cellspacing="0" cellpadding="0" class="swiftype-search-box">
                        <tbody><tr><td class="swiftype-input">
                            <input autocomplete="off" type="text" size="10" class="swiftype-input" name="search" title="search" dir="ltr" spellcheck="false" style="outline: none;" placeholder="Search SilverStripe...">
                        </td>
                            <td class="swiftype-search-button"><input type="submit" value="Search" class="swiftype-search-button" title="search"></td>
                            <td class="swiftype-clear-button"><div class="swiftype-clear-button" title="clear results">&nbsp;</div></td>
                        </tr></tbody>
                    </table>
                </form>
            </div>
        </div>

The site looks bad on mobile (I can’t paste a screenshot from my phone right now though)

Requires visibility:visible to be applied along with display:block to overwrite visibility:hidden applied by the .hidden selector.

Currently we are using an older version of API Gen. This is due to crashes during generation on the newer API Gen. Probably can be fixed by patching the bad code in framework, but potentially this has also been resolved in the upstream api gen repo.

Currently we are on 2.8 on a hotpatched fork at https://github.com/silverstripe-archive/apigen

We should upgrade to 4.1.2 https://github.com/ApiGen/ApiGen/releases/tag/v4.1.2

This is a bit more of a starting point of the conversation we'd like to have for "how do we document config?". At the moment the configuration system is a critical feature of the silverstripe framework API, and the actual configurable options lack any real formal documentation.

My suggestion would be to leverage the @config phpdoc identifier to build a list of configurable elements.

For instance, if I go to http://api.silverstripe.org/3.1/class-Director.html I would probably benefit from a "list of configurable options" section.

Seems there has been PRs to fix this though unsure if it's been deployed yet. The toolbar still seems broken under ssl on the current live site.

The old API generator inlined the PHP code - and it looks like many people miss that (see silverstripe/silverstripe-framework#7625).

This was dropped as part of the switch from Sami to Doctum (see #90).

There's a custom @config type hint, see example usage. It's unclear whether Doctum supports this.

https://api.silverstripe.org has a valid certificate through CloudFlare, but is somehow set up to always redirect to http://api.silverstripe.org. This isn't a good look, all of our own web properties should be served via HTTPS by default.

It is listed at http://api.silverstripe.org/4/SilverStripe/Forms/FieldList.html#method_removeByName as returning $this
It does not. FieldList::removeByname(..) returns null

Heading sizes and method sizes are too large (raised in silverstripe/silverstripe-framework#7625)

First, let me say thanks and great job on switching to SAMI so quickly!

However, there has been strong feedback from the community with regards to the new layout of the docs. Below is a summary of the features that are now missing, in a different place or otherwise disliked:

• • The native methods of the object are at the bottom, rather than pride-of-place at the top (#60)
• • The amount of noise from inherited methods and the sheer amount of space it takes up on a page are off-putting and often lead to developers giving up (#62)
• • A specific documentation integration - Dash - no longer works
• • A link to the file that contains the class is no longer present - I assume a link to GitHub would be acceptable in this case (#59)

It seems to me that most of this is templating rather than fundamental changes to the code.

An example is: http://api.silverstripe.org/4/SilverStripe/Forms/DropdownField.html

It appears to be trying to render the HTML inside the comment, which is then making the rest of the page unusable.

We do this on docs as well. Without that link, people don't know where to report bugs, and realise they can actually help fixing them ;)

Looking at https://www.google.co.nz/search?q=site:api.silverstripe.org&ei=A38CWvaYAsXg0gTm7qj4Cg&start=10&sa=N&biw=1234&bih=680 it seems like URLs without a language prefix are reasonably common, e.g.

http://api.silverstripe.org/3.1/class-DataList.html

Can we make the /en/ bit in the redirection URL regex optional?

Trying to bring up the documentation for TimeClass, will instead search for anything with TimeClass, meaning that DateTimeClass will come up first. In the case where the thing you're searching for is a prefix you can simply append a ::, however, this is not possible when it's a suffix that I'm aware of.

Expect results would probably be either a special identifier to signify start of the class name (think a regex style ^TimeClass, or mix and match the results from any search to not be alphabetical (that is, when you search for TimeClass, display a mix of results from both DateTimeClass and TimeClass, giving you a better chance of finding the results you will find helpful.

I added the "SilverStripe Apidocs" to my search bar in firefox.

Unfortunately it points to sami's default search url https://api.silverstripe.org/4/index.html?q={searchterm} instead of https://api.silverstripe.org/4/search.html?search={searchterm}

same for SS3 search and Master search.

This can be configured in /conf/themes/silverstripe/opensearch.twig

It might also be useful to add a favicon.

https://api.silverstripe.org/5/index.html

Only lists core (installer?) modules

It should list all supported modules (sink)

Means that heaps of api links in our changelogs for sink modules go nowhere e.g. CWP\CWP\Extensions\CwpSiteSummaryExtension (which is deprecated, though should still show in the 4 branch on api docs)

Stretch Goal

We mainly care about this for CMS5. If it's possible and easy to do it both for CMS4 and CMS5, do it. Otherwise, CMS5 is the priority.

PRs

Please take care to validate each of the branch mappings for each version! There are weird scenarios where it jumps a major release or where the same major release is available across multiple CMS versions. It is very likely I missed something.

• silverstripe/supported-modules#22 (CMS 5)
• silverstripe/supported-modules#23 (CMS 4)
• silverstripe/supported-modules#24 (CMS 3)
• #107
• #109

The API docs seem to be showing an inconsistency in the versions of released code.

eg.
If you install the current Silverstripe stable (4.0.3) as per the instructions, you'll get v1.0.3 of silverstripe/asset-admin

The 4.x API docs are currently showing code from what looks like the v1.1 branch (possibly this is also the master). There are differences in the methods / properties between the two branches, so you end up with the documentation being misleading compared to the stable release.

If you install the 4.1.0-rc2 branch of Silverstripe, you get the higher version of asset-admin which matches the API docs

As the 4.1 branch comes online, and runs in parallel with the 4.0 branch, there will presumably be more occurrences of this as the various dependencies may diverge between the two.

Should the documentation be further broken down to 4.0.x and 4.1.x to avoid this happening in the future?