From f0d47af165911de83ef93b40b08da16a4b00b82b Mon Sep 17 00:00:00 2001 From: Progi1984 Date: Mon, 9 Sep 2024 19:54:22 +0200 Subject: [PATCH] Github Action : Documentation --- .github/workflows/deploy.yml | 51 +++++++++++++++++ .gitignore | 2 + LICENSE | 21 +++++++ README.md | 57 +++++++++++++++++++ docs/changes/0.1.0.md | 17 ++++++ docs/credits.md | 7 +++ docs/index.md | 21 +++++++ docs/install.md | 21 +++++++ docs/usage/wmf.md | 107 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 50 ++++++++++++++++ 10 files changed, 354 insertions(+) create mode 100644 .github/workflows/deploy.yml create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/changes/0.1.0.md create mode 100644 docs/credits.md create mode 100644 docs/index.md create mode 100644 docs/install.md create mode 100644 docs/usage/wmf.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..bb4d4a5 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,51 @@ +name: Deploy + +on: + push: + branches: + - master + pull_request: + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + ### MkDocs + - name: Setup Python + uses: actions/setup-python@v2 + with: + python-version: 3.x + - name: Install Python Dependencies + run: pip install mkdocs-material autolink-references-mkdocs-plugin + - name: Build documentation + run: mkdocs build --site-dir public + ### PHPUnit + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: 7.1 + extensions: dom, xml + coverage: xdebug + - name: Create directory public/coverage + run: mkdir ./public/coverage + - name: Install PHP Dependencies + run: composer install --ansi --prefer-dist --no-interaction --no-progress + - name: Build Coverage Report + run: XDEBUG_MODE=coverage ./vendor/bin/phpunit -c ./ --coverage-text --coverage-html ./public/coverage + ### PHPDoc + #- name: Create directory public/docs + # run: mkdir ./public/docs + #- name: Install PhpDocumentor + # run: wget https://phpdoc.org/phpDocumentor.phar && chmod +x phpDocumentor.phar + #- name: Build Documentation + # run: ./phpDocumentor.phar run -d ./src -t ./public/docs + + ### Deploy + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/master' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public \ No newline at end of file diff --git a/.gitignore b/.gitignore index d45292a..bfa5383 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,7 @@ .phpunit.result.cache .php-cs-fixer.cache composer.lock +phpDocumentor.phar +public/ vendor/ \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a3380df --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019 PhpSpreadsheet Authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..da7548d --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +# WMF + +[![Latest Stable Version](https://poser.pugx.org/phpoffice/wmf/v)](https://packagist.org/packages/phpoffice/wmf) +[![Coverage Status](https://coveralls.io/repos/github/PHPOffice/WMF/badge.svg?branch=master)](https://coveralls.io/github/PHPOffice/WMF?branch=master) +[![Total Downloads](https://poser.pugx.org/phpoffice/wmf/downloads)](https://packagist.org/packages/phpoffice/wmf) +[![License](https://poser.pugx.org/phpoffice/wmf/license)](https://packagist.org/packages/phpoffice/wmf) +[![CI](https://github.com/PHPOffice/WMF/actions/workflows/php.yml/badge.svg)](https://github.com/PHPOffice/WMF/actions/workflows/php.yml) + +WMF is a library written in pure PHP that provides a set of classes to read WMF based file (like `.wmf` or `.emf` files). + +WMF is an open source project licensed under the terms of [MIT](https://github.com/PHPOffice/WMF/blob/master/LICENCE). WMF is aimed to be a high quality software product by incorporating [continuous integration and unit testing](https://github.com/PHPOffice/WMF/actions/workflows/php.yml). You can learn more about WMF by reading this Developers'Documentation and the [API Documentation](http://phpoffice.github.io/WMF/docs/develop/) + +If you have any questions, please ask on [StackOverFlow](https://stackoverflow.com/questions/tagged/phpoffice-wmf) + +Read more about WMF: + +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Contributing](#contributing) +- [Developers' Documentation](https://phpoffice.github.io/WMF/) + +## Features + +- Read files + + * WMF files + * (EMF files, not for the moment) + * (EMF+ files, not for the moment) + +## Requirements + +WMF requires the following: + +- PHP 7.1+ + +## Installation + +WMF is installed via [Composer](https://getcomposer.org/). +To [add a dependency](https://getcomposer.org/doc/04-schema.md#package-links) to WMF in your project, either + +Run the following to use the latest stable version +```sh +composer require phpoffice/wmf +``` +or if you want the latest unreleased version +```sh +composer require phpoffice/wmf:dev-master +``` + +## Contributing + +We welcome everyone to contribute to PHPWord. Below are some of the things that you can do to contribute. + +- [Fork us](https://github.com/PHPOffice/WMF/fork) and [request a pull](https://github.com/PHPOffice/WMF/pulls) to the [master](https://github.com/PHPOffice/WMF/tree/master) branch. +- Submit [bug reports or feature requests](https://github.com/PHPOffice/WMF/issues) to GitHub. +- Follow [@PHPOffice](https://twitter.com/PHPOffice) on Twitter. diff --git a/docs/changes/0.1.0.md b/docs/changes/0.1.0.md new file mode 100644 index 0000000..9abdf4f --- /dev/null +++ b/docs/changes/0.1.0.md @@ -0,0 +1,17 @@ +# 0.1.0 + +## Enhancements + +- Initial version by [@Progi1984](https://github/Progi1984) +- Enable/Disable Exceptions in [#3](https://github.com/PHPOffice/WMF/pull/3) by [@Progi1984](https://github/Progi1984) + +## Bug fixes + +- N/A + +## Miscellaneous + +- Github Action : PHP (PHPCSFixer / PHPStan / PHPUnit) in [#1](https://github.com/PHPOffice/WMF/pull/1) by [@Progi1984](https://github/Progi1984) +- Refactored WMF Reader in [#2](https://github.com/PHPOffice/WMF/pull/2) by [@Progi1984](https://github/Progi1984) +- Github Action : Documentation in [#4](https://github.com/PHPOffice/WMF/pull/4) by [@Progi1984](https://github/Progi1984) + \ No newline at end of file diff --git a/docs/credits.md b/docs/credits.md new file mode 100644 index 0000000..3c50316 --- /dev/null +++ b/docs/credits.md @@ -0,0 +1,7 @@ +## References + +### WMF + +### EMF + +### EMF+ \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5f86c4e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,21 @@ +# + +WMF is a library written in pure PHP that provides a set of classes to read WMF based file (like `.wmf` or `.emf` files). + +WMF is an open source project licensed under the terms of [MIT](https://github.com/PHPOffice/WMF/blob/master/LICENCE). WMF is aimed to be a high quality software product by incorporating [continuous integration and unit testing](https://github.com/PHPOffice/WMF/actions/workflows/php.yml). You can learn more about WMF by reading this Developers'Documentation and the [API Documentation](http://phpoffice.github.io/WMF/docs/develop/) + +## Features + +- Read files + + * WMF files + * (EMF files, not for the moment) + * (EMF+ files, not for the moment) + +## Contributing + +We welcome everyone to contribute to WMF. Below are some of the things that you can do to contribute: + +- [Fork us](https://github.com/PHPOffice/WMF/fork) and [request a pull](https://github.com/PHPOffice/WMF/pulls) to the [master](https://github.com/PHPOffice/WMF/tree/master) branch +- Submit [bug reports or feature requests](https://github.com/PHPOffice/WMF/issues) to GitHub +- Follow [@PHPOffice](https://twitter.com/PHPOffice) on Twitter \ No newline at end of file diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..ca73f24 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,21 @@ +# Installation + +## Requirements + +Mandatory: + +- PHP 7.1+ + +## Installation + +### Using Composer + +To install via [Composer](http://getcomposer.org), add the following lines to your `composer.json`: + +``` json +{ + "require": { + "phpoffice/wmf": "dev-master" + } +} +``` \ No newline at end of file diff --git a/docs/usage/wmf.md b/docs/usage/wmf.md new file mode 100644 index 0000000..69d80d1 --- /dev/null +++ b/docs/usage/wmf.md @@ -0,0 +1,107 @@ +# WMF + +You can load `.wmf` files. + +## Backends + +You can one of two current backends : `gd` or `imagick`. +If you don't know which one used, you can use the magic one. + +```php +load('sample.wmf'); +``` + +For next sample, I will use the magic one. + +## Methods + +### `getResource` + +The method returns the resource used in internal by the library. + +The `GD` backend returns a `GDImage` object or resource, depending the PHP version. +The `Imagick` backend returns a `Imagick` object. + +```php +load('sample.wmf'); + +var_dump($wmf->getResource()); +``` + +### `getMediaType` + +The method returns the media type for a WMF file + +```php +getMediaType(); + +echo 'The media type for a WMF file is ' . $$mediaType; +``` + +### `isWMF` + +The method allows to know if the file is supported by the library. + +```php +isWMF('sample.wmf'); + +echo 'The file sample.wmf ' . ($isWMF ? 'is a WMF file' : 'is not a WMF file'); +``` + +### `load` + +The method load a WMF file in the object + +```php +load('sample.wmf'); +``` + +### `save` + +The method transforms the loaded WMF file in an another image. + +```php +load('sample.wmf'); +$wmf->save('sample.png', 'png'); +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..03afe4c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,50 @@ +site_name: WMF +site_url: https://phpoffice.github.io/WMF +repo_url: https://github.com/PHPOffice/WMF +repo_name: PHPOffice/WMF +edit_uri: edit/master/docs/ + +## Theme +theme: + name: material + palette: + primary: grey + features: + - search.highlight + - search.suggest + +## Plugins +plugins: + - search + +## Config +extra: + generator: false +extra_javascript: + - https://polyfill.io/v3/polyfill.min.js?features=es6 +markdown_extensions: + ## Syntax highlighting + - pymdownx.highlight + - pymdownx.superfences + ## Support for emojis + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + ## Support for call-outs + - admonition + - pymdownx.details +use_directory_urls: false + +## Navigation +nav: + - Introduction: 'index.md' + - Install: 'install.md' + - Usage: + - WMF: 'usage/wmf.md' + - Credits: 'credits.md' + - Releases: + - '0.1.0 (WIP)': 'changes/0.1.0.md' + - Developers: + - 'Coveralls': 'https://coveralls.io/github/PHPOffice/WMF' + - 'Code Coverage': 'coverage/index.html' + - 'PHPDoc': 'docs/index.html' \ No newline at end of file