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 5c8be80..0c5a060 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,7 @@ .phpunit.cache .phpunit.result.cache composer.lock +phpDocumentor.phar -vendor/ \ No newline at end of file +public/ +vendor/ 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/composer.json b/composer.json index 33255d0..cc67ec6 100644 --- a/composer.json +++ b/composer.json @@ -18,6 +18,7 @@ ], "require": { "php": "^7.1|^8.0", + "ext-dom": "*", "ext-xml": "*" }, "require-dev": { diff --git a/docs/assets/mathjax.js b/docs/assets/mathjax.js new file mode 100644 index 0000000..73e9972 --- /dev/null +++ b/docs/assets/mathjax.js @@ -0,0 +1,17 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } + }; + + document$.subscribe(() => { + MathJax.typesetPromise() + }) + \ No newline at end of file diff --git a/docs/changes/0.1.0.md b/docs/changes/0.1.0.md new file mode 100644 index 0000000..8eaafd5 --- /dev/null +++ b/docs/changes/0.1.0.md @@ -0,0 +1,18 @@ +# 0.1.0 + +## Enhancements + +- Initial version by [@Progi1984](https://github/Progi1984) +- MathML Reader : Support for Semantics by [@Progi1984](https://github/Progi1984) in [#4](https://github.com/PHPOffice/Math/pull/4) + +## Bug fixes + +- N/A + +## Miscellaneous +- Github Actions : PHPCSFixer by [@Progi1984](https://github/Progi1984) in [#1](https://github.com/PHPOffice/Math/pull/1) +- Github Actions : PHPStan by [@Progi1984](https://github/Progi1984) in [#2](https://github.com/PHPOffice/Math/pull/2) +- Removed dependency friendsofphp/php-cs-fixer by [@Progi1984](https://github/Progi1984) in [#3](https://github.com/PHPOffice/Math/pull/3) +- Github Actions : Dependabot by [@Progi1984](https://github/Progi1984) in [#5](https://github.com/PHPOffice/Math/pull/5) +- Bump actions/checkout from 2 to 4 by [@dependabot](https://github/dependabot) in [#6](https://github.com/PHPOffice/Math/pull/6) +- Added documentation (MkDocs / Coverage / PHPDoc) by [@Progi1984](https://github/Progi1984) in [#7](https://github.com/PHPOffice/Math/pull/7) \ No newline at end of file diff --git a/docs/credits.md b/docs/credits.md new file mode 100644 index 0000000..34795ba --- /dev/null +++ b/docs/credits.md @@ -0,0 +1,8 @@ +## References + +### MathML + +- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/MathML) + +### OfficeMathML + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..339c460 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,59 @@ +# + +Math is a library written in pure PHP that provides a set of classes to manipulate different formula file formats, i.e. [MathML](https://en.wikipedia.org/wiki/MathML) and [Office MathML (OOML)](https://en.wikipedia.org/wiki/Office_Open_XML_file_formats#Office_MathML_(OMML)). + +Math is an open source project licensed under the terms of [MIT](https://github.com/PHPOffice/PHPWord/blob/master/LICENCE). Math is aimed to be a high quality software product by incorporating [continuous integration and unit testing](https://github.com/PHPOffice/Math/actions/workflows/php.yml). You can learn more about Math by reading this Developers'Documentation and the [API Documentation](http://phpoffice.github.io/PHPWord/docs/develop/) + +## Features + +- Insert elements: + + * Basic : + + * Identifier : a + * Operator : + + * Numeric : 2 + + * Simple : + + * Fraction : a3 + * Superscript : a3 + + * Architectural : + + * Row + * Semantics + +## Support + +### Readers + +| Features | | MathML | Office MathML | +|---------------------------|----------------------|:----------------:|:----------------:| +| **Basic** | Identifier | :material-check: | :material-check: | +| | Operator | :material-check: | :material-check: | +| | Numeric | :material-check: | :material-check: | +| **Simple** | Fraction | :material-check: | :material-check: | +| | Superscript | :material-check: | | +| **Architectural** | Row | :material-check: | | +| | Semantics | :material-check: | | + +### Writers + +| Features | | MathML | Office MathML | +|---------------------------|----------------------|:----------------:|:----------------:| +| **Basic** | Identifier | :material-check: | :material-check: | +| | Operator | :material-check: | :material-check: | +| | Numeric | :material-check: | :material-check: | +| **Simple** | Fraction | :material-check: | :material-check: | +| | Superscript | :material-check: | | +| **Architectural** | Row | :material-check: | :material-check: | +| | Semantics | | | + +## Contributing + +We welcome everyone to contribute to Math. Below are some of the things that you can do to contribute: + +- [Fork us](https://github.com/PHPOffice/Math/fork) and [request a pull](https://github.com/PHPOffice/Math/pulls) to the [master](https://github.com/PHPOffice/Math/tree/master) branch +- Submit [bug reports or feature requests](https://github.com/PHPOffice/Math/issues) to GitHub +- Follow [@PHPOffice](https://twitter.com/PHPOffice) on Twitter diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..6aca509 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,25 @@ +# Installation + +## Requirements + +Mandatory: + +- PHP 7.1+ +- PHP [DOM extension](http://php.net/manual/en/book.dom.php) +- PHP [XML Parser extension](http://www.php.net/manual/en/xml.installation.php) +- PHP [XMLWriter extension](http://php.net/manual/en/book.xmlwriter.php) + + +## Installation + +### Using Composer + +To install via [Composer](http://getcomposer.org), add the following lines to your `composer.json`: + +``` json +{ + "require": { + "phpoffice/math": "dev-master" + } +} +``` \ No newline at end of file diff --git a/docs/usage/elements/fraction.md b/docs/usage/elements/fraction.md new file mode 100644 index 0000000..b73db19 --- /dev/null +++ b/docs/usage/elements/fraction.md @@ -0,0 +1,61 @@ +## Usage + +To create a fraction, use the `PhpOffice\Math\Element\Fraction` class. + +### Methods +#### getDenominator + +The method has no parameter. + +#### getNumerator + +The method has no parameter. + +#### setDenominator + +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +#### setNumerator + +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +## Example + +### Math + + + a + 3 + + + +### XML +``` xml + + + a + 3 + + +``` + +### PHP + +``` php +setDenominator(new Element\Identifier('a')); +$fraction->setNumerator(new Element\Numeric(3)); + +$math->add($fraction); +``` \ No newline at end of file diff --git a/docs/usage/elements/identifier.md b/docs/usage/elements/identifier.md new file mode 100644 index 0000000..070a075 --- /dev/null +++ b/docs/usage/elements/identifier.md @@ -0,0 +1,43 @@ +## Usage + +To create an identifier, use the `PhpOffice\Math\Element\Identifier` class. + +### Methods +#### getValue + +The method has no parameter. + +#### setValue + +The method has one parameter : + +* `string` **$value** + +## Example + +### Math + + a + + +### XML +``` xml + + a + +``` + +### PHP + +``` php +add($identifier); +``` \ No newline at end of file diff --git a/docs/usage/elements/numeric.md b/docs/usage/elements/numeric.md new file mode 100644 index 0000000..200ec18 --- /dev/null +++ b/docs/usage/elements/numeric.md @@ -0,0 +1,43 @@ +## Usage + +To create a numeric, use the `PhpOffice\Math\Element\Numeric` class. + +### Methods +#### getValue + +The method has no parameter. + +#### setValue + +The method has one parameter : + +* `float` **$value** + +## Example + +### Math + + 3 + + +### XML +``` xml + + 3 + +``` + +### PHP + +``` php +add($identifier); +``` \ No newline at end of file diff --git a/docs/usage/elements/operator.md b/docs/usage/elements/operator.md new file mode 100644 index 0000000..9816eb7 --- /dev/null +++ b/docs/usage/elements/operator.md @@ -0,0 +1,43 @@ +## Usage + +To create an operator, use the `PhpOffice\Math\Element\Operator` class. + +### Methods +#### getValue + +The method has no parameter. + +#### setValue + +The method has one parameter : + +* `string` **$value** + +## Example + +### Math + + + + + +### XML +``` xml + + + + +``` + +### PHP + +``` php +add($identifier); +``` \ No newline at end of file diff --git a/docs/usage/elements/row.md b/docs/usage/elements/row.md new file mode 100644 index 0000000..32a9fd7 --- /dev/null +++ b/docs/usage/elements/row.md @@ -0,0 +1,62 @@ +## Usage + +To create a row, use the `PhpOffice\Math\Element\Row` class. + +### Methods +#### add + +The method add an element to the row. +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +#### getElements + +The method return all elements of the row. + +#### remove + +The method remove an element to the row. +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +## Example + +### Math + + + 1 + + + K + + + +### XML +``` xml + + + 1 + + + K + + +``` + +### PHP + +``` php +add(new Element\Numeric(1)); +$row->add(new Element\Operator('+')); +$row->add(new Element\Identifier('K')); + +$math->add($row); +``` \ No newline at end of file diff --git a/docs/usage/elements/semantics.md b/docs/usage/elements/semantics.md new file mode 100644 index 0000000..4015be0 --- /dev/null +++ b/docs/usage/elements/semantics.md @@ -0,0 +1,81 @@ +## Usage + +To create a semantics, use the `PhpOffice\Math\Element\Semantics` class. + +### Methods +#### add + +The method add an element to the `semantics` element. +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +#### addAnnotation + +The method add an annotation to the `semantics` element. +The method has two parameters : + +* `string` **$encoding** +* `string` **$annotation** + +#### getAnnotation + +The method return an annotation based on its encoding. +The method has one parameter : + +* `string` **$encoding** + +#### getAnnotations + +The method return alls annotation of the `semantics` element. +The method has no parameter. + +#### getElements + +The method return all elements of the `semantics` element. + +#### remove + +The method remove an element to the `semantics` element. +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +## Example + +### Math + + + y + + y + + + +### XML +``` xml + + + y + + y + + +``` + +### PHP + +``` php +add(new Element\Identifier('y')); +$semantics->addAnnotation('application/x-tex', ' y '); + +$math->add($semantics); +``` \ No newline at end of file diff --git a/docs/usage/elements/superscript.md b/docs/usage/elements/superscript.md new file mode 100644 index 0000000..fc91c20 --- /dev/null +++ b/docs/usage/elements/superscript.md @@ -0,0 +1,61 @@ +## Usage + +To attach a superscript to an expression, use the `PhpOffice\Math\Element\Superscript` class. + +### Methods +#### getBase + +The method has no parameter. + +#### getSuperscript + +The method has no parameter. + +#### setBase + +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +#### setSuperscript + +The method has one parameter : + +* `PhpOffice\Math\Element\AbstractElement` **$element** + +## Example + +### Math + + + X + 2 + + + +### XML +``` xml + + + X + 2 + + +``` + +### PHP + +``` php +setBase(new Element\Identifier('X')); +$superscript->setSuperscript(new Element\Numeric(2)); + +$math->add($superscript); +``` \ No newline at end of file diff --git a/docs/usage/readers.md b/docs/usage/readers.md new file mode 100644 index 0000000..4956857 --- /dev/null +++ b/docs/usage/readers.md @@ -0,0 +1,50 @@ + +## Readers +### MathML +The name of the reader is `MathML`. + +``` php +read( + ' + + + a + ' +); +``` + +### OfficeMathML +The name of the reader is `OfficeMathML`. + +``` php +read( + ' + + + π + 2 + + + ' +); +``` + +## Methods + +### read + +The method has one parameter : + +* `string` **$content** + +The method returns a `PhpOffice\Math\Math` object. \ No newline at end of file diff --git a/docs/usage/writers.md b/docs/usage/writers.md new file mode 100644 index 0000000..58dbb6a --- /dev/null +++ b/docs/usage/writers.md @@ -0,0 +1,46 @@ + +## Writers +### MathML +The name of the writer is `MathML`. + +``` php +add(new Element\Operator('+')); + +$writer = new MathML(); +$output = $writer->write($math); +``` + +### OfficeMathML + +The name of the writer is `OfficeMathML`. + +``` php +add(new Element\Operator('+')); + +$writer = new OfficeMathML(); +$output = $writer->write($math); +``` + +## Methods + +### writer + +The method has one parameter : + +* `PhpOffice\Math\Math` **$math** + +The method returns a `string`. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d4d88f9 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,64 @@ +site_name: Math +site_url: https://phpoffice.github.io/Math +repo_url: https://github.com/PHPOffice/Math +repo_name: PHPOffice/Math +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: + - assets/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js +markdown_extensions: + ## Syntax highlighting + - pymdownx.highlight + - pymdownx.superfences + ## Support for Math + - pymdownx.arithmatex: + generic: true + ## 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: + - Elements: + - Fraction: 'usage/elements/fraction.md' + - Identifier: 'usage/elements/identifier.md' + - Numeric: 'usage/elements/numeric.md' + - Operator: 'usage/elements/operator.md' + - Row: 'usage/elements/row.md' + - Semantics: 'usage/elements/semantics.md' + - Superscript: 'usage/elements/superscript.md' + - Readers: 'usage/readers.md' + - Writers: 'usage/writers.md' + - Credits: 'credits.md' + - Releases: + - '0.1.0 (WIP)': 'changes/0.1.0.md' + - Developers: + - 'Coveralls': 'https://coveralls.io/github/PHPOffice/Math' + - 'Code Coverage': 'coverage/index.html' + - 'PHPDoc': 'docs/index.html' \ No newline at end of file diff --git a/phpunit.xml.dist b/phpunit.xml.dist index ddf5283..3cfe957 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -8,7 +8,7 @@ processIsolation="false" stopOnFailure="false"> - + ./tests/Math