Skip to content

Commit 275c53f

Browse files
nfebenfebe
authored
Introduced phpdoc (#323)
* content update : readme & contribution guide Signed-off-by: fenn-cs <[email protected]> * introduced phpdoc Signed-off-by: fenn-cs <[email protected]> * content update : readme & phpdoc - automatic docs Signed-off-by: fenn-cs <[email protected]> * added generate and publish source docs action Signed-off-by: fenn-cs <[email protected]>
1 parent 13dcc6f commit 275c53f

File tree

8 files changed

+138
-14
lines changed

8 files changed

+138
-14
lines changed

‎.github/CONTRIBUTING.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,7 @@ Before you report an issue, please search through the existing issues here on
3131
GitHub to see if your issue is already reported or fixed to make sure you are
3232
not reporting a duplicated issue.
3333

34-
Also please make sure you have the latest version of this package and check if
35-
the issue still exists.
34+
In addition, make sure you have the latest version of this package to ensure the issue still exists.
3635

3736

3837
# Contribute code, bug fixes or documentation (pull requests)
@@ -60,8 +59,7 @@ have a chance of keeping on top of things:
6059
8. Add a changelog entry.
6160
9. [Commit](#git-commits) and push your changes.
6261
10. [Create a pull request](https://help.github.com/articles/about-pull-requests/)
63-
for your changes. Check that the Travis build is green. (If it is not, fix the
64-
problems listed by Travis.)
62+
for your changes. Check that CI checks implemented with `Github Actions` pass. (Otherwise, corrected listed issues to ensure checks pass.)
6563
We have provided a template for pull requests as well.
6664
11. [Request a review](https://help.github.com/articles/about-pull-request-reviews/).
6765
11. Together with your reviewer, polish your changes until they are ready to be

‎.github/workflows/core-docs.yml

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: Publish Core Docs
2+
on: [push, pull_request]
3+
jobs:
4+
make-restapi-docs:
5+
name: Checkout phpList core and generate docs using `phpDocumentor`
6+
runs-on: ubuntu-20.04
7+
steps:
8+
- name: Checkout
9+
uses: actions/checkout@v2
10+
- name: Setup PHP, with composer and extensions
11+
uses: shivammathur/setup-php@v2 #https://github.com/shivammathur/setup-php
12+
with:
13+
php-version: 7.4
14+
extensions: mbstring, dom, fileinfo, mysql
15+
- name: Get composer cache directory
16+
id: composer-cache
17+
run: echo "::set-output name=dir::$(composer config cache-files-dir)"
18+
- name: Cache composer dependencies
19+
uses: actions/cache@v2
20+
with:
21+
path: ${{ steps.composer-cache.outputs.dir }}
22+
# Use composer.json for key, if composer.lock is not committed.
23+
# key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
24+
key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
25+
restore-keys: ${{ runner.os }}-composer-
26+
- name: Install current dependencies from composer.lock
27+
run: composer install
28+
- name: Install phpDocumentor
29+
run: |
30+
wget https://phpdoc.org/phpDocumentor.phar
31+
chmod +x phpDocumentor.phar
32+
mv phpDocumentor.phar /usr/local/bin/phpDocumentor
33+
- name: Generate documentation
34+
run: composer run-php-documentor
35+
- name: zip phpdocumentor dir
36+
run: zip -r phpdocumentor.zip docs/phpdocumentor
37+
- name: Upload generated doc files
38+
uses: actions/upload-artifact@v2
39+
with:
40+
name: doc-files
41+
path: phpdocumentor.zip
42+
deploy-docs:
43+
name: Deploy Core Docs.
44+
runs-on: ubuntu-20.04
45+
needs: make-restapi-docs
46+
steps:
47+
- name: Checkout phplist/core-docs
48+
uses: actions/checkout@v2
49+
with:
50+
repository: phpList/core-docs
51+
fetch-depth: 0
52+
token: ${{ secrets.PUSH_CORE_DOCS }}
53+
- name: Restore REST API Spec
54+
uses: actions/download-artifact@v2
55+
with:
56+
name: doc-files
57+
- name: unzip phpdocumentor
58+
run: |
59+
unzip phpdocumentor.zip
60+
rm phpdocumentor.zip
61+
- name: List Files
62+
run: ls
63+
- name: Move Files
64+
run: mv docs/phpdocumentor/* .
65+
- name: Check if updates/changes.
66+
run: git status --porcelain > repo-changes.txt
67+
- name: Verify updates.
68+
id: allow-deploy
69+
run: |
70+
if [ -s repo-changes.txt ]; then echo "Updates made to documentation"; echo '::set-output name=DEPLOY::true'; else echo "No updates made to documentation deployment would be skipped."; echo '::set-output name=DEPLOY::false'; fi
71+
- name: Commit changes and deply
72+
if: ${{ steps.allow-deploy.outputs.DEPLOY == 'true' }}
73+
run: |
74+
rm -rf docs
75+
git config user.name "github-actions"
76+
git config user.email "[email protected]"
77+
git add .
78+
git commit -s -m "phplist/core docs deployment `date`"
79+
git push

‎.gitignore

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,6 @@
1212
/nbproject
1313
/var/
1414
/vendor/
15-
.vagrant
15+
/docs/phpdocumentor
16+
.vagrant
17+
.phpdoc/

‎PHPDOC.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Class Documentation with PHPDoc
2+
3+
We use [phpdoc](phpdoc.org) to automatically generate documentation for our annotated classes.
4+
5+
So to be able to generate or update our class docs you would need to download and install `phpDocumentor` globally (for system wide use) as shown below:
6+
7+
1. `cd ~` [*Optional : it's recommended to navigate to your home dir before downloading `phpDocumentor` as shown in step 2*]
8+
2. `wget https://phpdoc.org/phpDocumentor.phar`
9+
3. `chmod +x phpDocumentor.phar`
10+
4. `mv phpDocumentor.phar /usr/local/bin/phpDocumentor`
11+
12+
*Possibility : In case you don't want to install `phpDocumentor` globally you can skip step 4, however you would need to run `phpDocumentor` from whatever path it was installed in.*
13+
14+
*Tip : You might need to run step four as root on some systems. That is : `sudo mv phpDocumentor.phar /usr/local/bin/phpDocumentor`*
15+
16+
## Generate Docs
17+
18+
If you did install `phpDocumentor` globally as specified above then you can generate class docs as follows.
19+
Run : `composer run-php-documentor`
20+
21+
22+
23+
*Note : `composer generate docs` would only work if you installed `phpDocumentor` globally, if you did not run : `custom/path/phpDocumentor -d 'src,tests' -t docs/phpdoc` to generate docs*
24+
25+
*Where `custom/path/` is the location where you downloaded `phpDocumentor`*
26+

‎README.md

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,23 +28,20 @@ following responsibilities:
2828
* tasks to create and update the DB schema
2929

3030
Please note that this module does not provide a web frontend or a REST API.
31-
There are the separate modules `phpList/web-frontend` and `phpList/rest-api`
31+
There are the separate modules [`phpList/web-frontend`](https://github.com/phpList/web-frontend) and [`phpList/rest-api`](https://github.com/phpList/rest-api)
3232
for these tasks.
3333

3434
This module should not be modified locally. It should be updated via Composer.
3535

3636

3737
## Installation
3838

39-
Please install this package via Composer from within the
40-
[phpList base distribution](https://github.com/phpList/base-distribution),
41-
which also has more detailed installation instructions in the README.
39+
Since this package is only a service required to run a full installation of **phpList 4**, the recommended way of installing this package is to run `composer install` from within the [phpList base distribution](https://github.com/phpList/base-distribution) which requires this package. [`phpList/base-distribution`](https://github.com/phpList/base-distribution) containrs detailed installation instructions in its [README](https://github.com/phpList/base-distribution/blob/master/README.md).
4240

4341

4442
## Contributing to this package
4543

46-
Please read the [contribution guide](.github/CONTRIBUTING.md) on how to
47-
contribute and how to run the unit tests and style checks locally.
44+
Contributions to phpList repositories are highly welcomed! To get started please take a look at the [contribution guide](.github/CONTRIBUTING.md). It contains everything you would need to make your first contribution including how to run local style checks and run tests.
4845

4946
### Code of Conduct
5047

@@ -55,8 +52,9 @@ this code.
5552

5653
## Structure
5754

58-
* [class structure overview](docs/ClassStructure.md)
59-
* [graphic domain model](docs/DomainModel/DomainModel.svg) and
55+
* [Class Docs][docs/phpdoc/]
56+
* [Class structure overview](docs/ClassStructure.md)
57+
* [Graphic domain model](docs/DomainModel/DomainModel.svg) and
6058
a [description of the domain entities](docs/DomainModel/Entities.md)
6159

6260

@@ -69,7 +67,7 @@ Please first set the database credentials in `config/parameters.yml`.
6967

7068
### Development
7169

72-
For running the application in development mode using the built-in PHP server,
70+
To run the application in development mode using PHP's built-in server,
7371
use this command:
7472

7573
```bash
@@ -81,6 +79,12 @@ already in use, on the next free port after 8000).
8179

8280
You can stop the server with CTRL + C.
8381

82+
#### Development and Documentation
83+
84+
We use `phpDocumentor` to automatically generate documentation for classes. To make this process efficient and easier, you are required to properly "document" your `classes`,`properties`, `methods` ... by annotating them with [docblocks](https://docs.phpdoc.org/latest/guide/guides/docblocks.html).
85+
86+
More about generatings docs in [PHPDOC.md](PHPDOC.md)
87+
8488
### Testing
8589

8690
To run the server in testing mode (which normally will only be needed for the

‎composer.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,9 @@
9090
],
9191
"post-update-cmd": [
9292
"@update-configuration"
93+
],
94+
"run-php-documentor": [
95+
"phpDocumentor -d 'src,tests'"
9396
]
9497
},
9598
"extra": {

‎php.zip

579 KB
Binary file not shown.

‎phpdoc.xml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<phpdocumentor
3+
configVersion="3"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5+
xmlns="https://www.phpdoc.org"
6+
>
7+
<title>phpList/Core Docs</title>
8+
<paths>
9+
<output>docs/phpdocumentor</output>
10+
</paths>
11+
12+
</phpdocumentor>

0 commit comments

Comments
 (0)