Skip to content

Commit c385158

Browse files
HackwarHackwar
authored
Merge pull request #25 from Hackwar/drone
2 parents 8d9524f + 520f4ff commit c385158

File tree

13 files changed

+2415
-15
lines changed

13 files changed

+2415
-15
lines changed

‎.drone.yml‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
kind: pipeline
3+
name: deploy_static_assets
4+
5+
clone:
6+
7+
steps:
8+
- name: prepare_package
9+
image: joomlaprojects/docker-images:packager
10+
commands:
11+
- mkdir build
12+
- cp -r -v archived.html css/ images/ img/ js/ index.html results.html robots.txt 403.html 404.html .htaccess ./build
13+
14+
- name: deploy_documentation
15+
image: debian:stable-slim
16+
environment:
17+
ssh_password:
18+
from_secret: ssh_password
19+
ssh_user:
20+
from_secret: ssh_user
21+
ssh_host:
22+
from_secret: ssh_host
23+
commands:
24+
- apt update && apt install -y rclone openssh-client
25+
- rclone config create api sftp host $ssh_host user $ssh_user pass $ssh_password port 22 use_insecure_cipher true disable_hashcheck true
26+
- rclone sync ./build/ api:/home/api/public_html -v --exclude "cms-2.5" --exclude "cms-3" --exclude "cms-4" --exclude "framework-1" --exclude "framework-2"
27+
28+
trigger:
29+
branch:
30+
- master
31+
event:
32+
- push
33+
34+
---
35+
kind: pipeline
36+
name: build_documentation
37+
38+
clone:
39+
40+
steps:
41+
- name: parameter_check1
42+
image: debian:stable-slim
43+
commands:
44+
- |
45+
if [ "$JTYPE" = "framework" ]; then
46+
exit 0
47+
fi
48+
- echo "JTYPE parameter is missing. Allowed values [framework, cms]"
49+
- exit 1
50+
51+
- name: parameter_check2
52+
image: debian:stable-slim
53+
commands:
54+
- |
55+
if [ $JVERSION > 0 ]; then
56+
exit 0
57+
fi
58+
- echo 'JVERSION parameter is missing.'
59+
- exit 1
60+
61+
- name: prepare
62+
image: joomlaprojects/docker-images:php7.4
63+
commands:
64+
- composer install
65+
- git config --global advice.detachedHead false
66+
- |
67+
if [ "$JTYPE" = "framework" ]; then
68+
vendor/bin/robo repos:checkout --fw=$JVERSION
69+
fi
70+
- |
71+
if [ "$JTYPE" = "cms" ]; then
72+
git clone https://github.com/joomla/joomla-cms.git ./repos/joomla-cms
73+
cd repos/joomla-cms
74+
git checkout tags/$JVERSION
75+
fi
76+
77+
- name: generate_documentation
78+
image: phpdoc/phpdoc
79+
commands:
80+
- |
81+
if [ "$JTYPE" = "framework" ]; then
82+
phpdoc -d "./repos/*/src" -t "./build/framework-$JVERSION/" --template "./" --title "Joomla! Framework $JVERSION.x API" -i "./repos/string/src/phputf8" --setting=graphs.enabled=true
83+
fi
84+
- |
85+
if [ "$JTYPE" = "cms" ]; then
86+
export MINORVERSION=${JVERSION%.*}
87+
export MAJORVERSION=${MINORVERSION%.*}
88+
phpdoc -d "./repos/joomla-cms/libraries/src" -t "./build/cms-$MAJORVERSION/" --template "./" --title "Joomla! CMS $MINORVERSION.x API" --setting=graphs.enabled=true
89+
fi
90+
91+
- name: deploy_documentation
92+
image: debian:stable-slim
93+
environment:
94+
ssh_password:
95+
from_secret: ssh_password
96+
ssh_user:
97+
from_secret: ssh_user
98+
ssh_host:
99+
from_secret: ssh_host
100+
commands:
101+
- apt update && apt install -y rclone openssh-client
102+
- rclone config create api sftp host $ssh_host user $ssh_user pass $ssh_password port 22 use_insecure_cipher true disable_hashcheck true
103+
- |
104+
if [ "$JTYPE" = "framework" ]; then
105+
rclone sync ./build/framework-$JVERSION/ api:/home/api/public_html/framework-$JVERSION/ -v
106+
fi
107+
- |
108+
if [ "$JTYPE" = "cms" ]; then
109+
export MINORVERSION=${JVERSION%.*}
110+
export MAJORVERSION=${MINORVERSION%.*}
111+
rclone sync ./build/cms-$MAJORVERSION/ api:/home/api/public_html/cms-$MAJORVERSION/ -v
112+
fi
113+
-
114+
115+
trigger:
116+
branch:
117+
- master
118+
event:
119+
- custom
120+
121+
---
122+
kind: signature
123+
hmac: 5b71082bf6335a04e8852a4231b1991fad92ddc6e5492e8b1e83b28bc4192f9f
124+
125+
...

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,9 @@
44
.settings
55
.DS_Store
66
.idea
7+
8+
/.phpdoc/
9+
/api-docs/
10+
/build/
11+
/repos/
12+
/vendor/

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,18 @@ The following directories are no longer indexed by search engines but are still
3030
- `1.5` contains the API documentation for the Joomla! 1.5 branch
3131
- `11.4` contains the API documentation for the Joomla! Platform 11.4 release
3232
- `12.1` contains the API documentation for the Joomla! Platform 12.1 release
33+
34+
## Deployment
35+
Deployment is done with Drone CI and consists of 2 pipelines.
36+
- The first pipeline is triggered when a PR or commit is pushed to the master branch. This deploys the static files of the site, which means mainly the homepage.
37+
- The second pipeline is triggered when a custom build is triggered from ci.joomla.org. This needs additional parameters and wont work without it!
38+
39+
### CMS API documentation deployment
40+
To generate the CMS API documentation, go to https://ci.joomla.org/joomla/api.joomla.org and click on "New Build" in the top right corner. In the popup, set "Branch" to "master" and type in "JTYPE" for "key" under "Parameters" and "cms" as value for that key. **You have to click "add" to actually add this!** Besides saving the parameter, this also adds another parameter and we have to type in "JVERSION" as key and the tag-name of the release as value. Remember to click "Add" again!
41+
42+
This checks out the tag from joomla/joomla-cms and then builds the documentation with phpDocumentor including the class hierarchy diagram. This is then automatically uploaded to the api.joomla.org server.
43+
44+
### Framework API documentation deployment
45+
To generate the CMS API documentation, go to https://ci.joomla.org/joomla/api.joomla.org and click on "New Build" in the top right corner. In the popup, set "Branch" to "master" and type in "JTYPE" for "key" under "Parameters" and "framework" as value for that key. **You have to click "add" to actually add this!** Besides saving the parameter, this also adds another parameter and we have to type in "JVERSION" as key and the major version of the framework you want to build. Remember to click "Add" again!
46+
47+
This checks out all framework packages from the packages.yml file with the Robo.li script (vendor/bin/robo checkout:repos --fw=2) into one common folder, then runs phpDocumentor on this, including the class hierarchy diagram, and then uploads that to the corresponding folder on api.joomla.org. **Right now this only supports the version 2 of the framework.**

‎RoboFile.php‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
<?php
2+
/**
3+
* @package Joomla.Internal-Documentation
4+
*
5+
* @copyright Copyright (C) 2022 Open Source Matters, Inc. All rights reserved.
6+
* @license GNU General Public License version 2 or later; see LICENSE.txt
7+
*/
8+
9+
use Robo\Symfony\ConsoleIO;
10+
use Robo\Tasks;
11+
12+
require_once 'vendor/autoload.php';
13+
14+
/**
15+
* Modern php task runner for Joomla! Browser Automated Tests execution
16+
*
17+
* @package RoboFile
18+
*
19+
* @since 1.0
20+
*/
21+
class RoboFile extends Tasks
22+
{
23+
protected $config;
24+
25+
public function buildApidocu(ConsoleIO $io, $opts = ['fw' => '2'])
26+
{
27+
$this->reposCheckout($io, $opts);
28+
$this->generatePhpdocu($io, $opts);
29+
}
30+
31+
public function reposCheckout(ConsoleIO $io, $opts = ['fw' => '2'])
32+
{
33+
$this->say('Checking out correct version of the framework repos');
34+
35+
if (!$this->config)
36+
{
37+
$this->config = \Symfony\Component\Yaml\Yaml::parseFile(__DIR__ . '/packages.yml');
38+
}
39+
40+
$taglessDirectories = [
41+
'datetime',
42+
'mediawiki-api',
43+
'renderer',
44+
'symfony-event-dispatcher-bridge'
45+
];
46+
47+
foreach ($this->config['packages'] as $name => $package)
48+
{
49+
if (is_null($package) || (is_array($package) && !(isset($package['deprecated']) || isset($package['abandoned']))))
50+
{
51+
$repo = $name;
52+
53+
if (isset($package['repo']))
54+
{
55+
$repo = $package['repo'];
56+
}
57+
58+
$this->say('Repository: ' . $name . ' (' . $repo . ')');
59+
60+
if (!is_dir(__DIR__ . '/repos/' . $name))
61+
{
62+
$this->say('Clone repo');
63+
system('git clone https://github.com/joomla-framework/' . $repo . '.git ./repos/' . $name);
64+
}
65+
66+
chdir(__DIR__ . '/repos/' . $name);
67+
$tag = system('git tag -l --sort=creatordate "' . $opts['fw'] . '.*"');
68+
system("git checkout tags/$tag");
69+
70+
chdir(__DIR__ . '/');
71+
}
72+
}
73+
74+
$this->say('Repos have been checked out.');
75+
}
76+
77+
public function generatePhpdocu(ConsoleIO $io, $opts = ['fw' => '2'])
78+
{
79+
$this->say('Generate API documentation using phpDocumentor for Joomla Framework ' . $opts['fw'] . '.x packages');
80+
$this->_exec('php phpDocumentor.phar -d ./repos/*/src -t ./build/api-docs/v' . $opts['fw'] . '/ --template ./ --title "Joomla! Framework ' . $opts['fw'] . '.x API" -i ./repos/string/src/phputf8');
81+
}
82+
}

‎base/macros.html.twig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,6 @@
5353
{{ element.description }}
5454
{% endif %}
5555
</div>
56-
{% if path(element) and type not in ['function', 'constant'] %}<a href="{{ path(element) }}" class="element__details">« More »</a>{% endif %}
56+
{% if path(element) and type not in ['function', 'constant'] %}<a href="{{ path(element|route('url')) }}" class="element__details">« More »</a>{% endif %}
5757
</div>
5858
{% endmacro %}

‎composer.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "joomla/api.joomla.org",
3+
"description": "Code for api.joomla.org",
4+
"homepage": "http://github.com/joomla/api.joomla.org",
5+
"license": "GPL-2.0-or-later",
6+
"require": {
7+
"php": "^7.4"
8+
},
9+
"require-dev": {
10+
"consolidation/robo": "~3.0.4"
11+
},
12+
"config": {
13+
"platform": {
14+
"php": "7.4.0"
15+
}
16+
}
17+
}

0 commit comments

Comments
 (0)