Added documentation (MkDocs / Coverage / PHPDoc)

PHPOffice · Sep 25, 2023 · 74d0438 · 74d0438
1 parent 6a3cf17
commit 74d0438
Show file tree

Hide file tree

Showing 20 changed files with 758 additions and 2 deletions.
diff --git a/.github/workflows/deploy.yml 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
diff --git a/.gitignore b/.gitignore
@@ -2,5 +2,7 @@
 .phpunit.cache
 .phpunit.result.cache
 composer.lock
+phpDocumentor.phar
 
-vendor/
+public/
+vendor/
diff --git a/LICENSE 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.
diff --git 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
@@ -0,0 +1,17 @@
+window.MathJax = {
+    tex: {
+      inlineMath: [["\\(", "\\)"]],
+      displayMath: [["\\[", "\\]"]],
+      processEscapes: true,
+      processEnvironments: true
+    },
+    options: {
+      ignoreHtmlClass: ".*|",
+      processHtmlClass: "arithmatex"
+    }
+  };
+
+  document$.subscribe(() => {
+    MathJax.typesetPromise()
+  })
+
diff --git a/docs/changes/0.1.0.md 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)
diff --git a/docs/credits.md 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
@@ -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 : <math display="inline"><mi>a</mi></math>
+        * Operator : <math display="inline"><mo>+</mo></math>
+        * Numeric : <math display="inline"><mn>2</mn></math>
+
+    * Simple :
+
+        * Fraction : <math display="inline"><mfrac><mi>a</mi><mn>3</mn></mfrac></math>
+        * Superscript : <math display="inline"><msup><mi>a</mi><mn>3</mn></msup></math>
+
+    * 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
@@ -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"
+    }
+}
+```
diff --git a/docs/usage/elements/fraction.md 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
+<math display="block">
+  <mfrac>
+      <mi>a</mi>
+      <mn>3</mn>
+  </mfrac>
+</math>
+
+### XML
+``` xml
+<math display="block">
+  <mfrac>
+      <mi>a</mi>
+      <mn>3</mn>
+  </mfrac>
+</math>
+```
+
+### PHP
+
+``` php
+<?php
+
+use PhpOffice\Math\Element;
+use PhpOffice\Math\Math;
+
+$math = new Math();
+
+$fraction = new Element\Fraction();
+$fraction->setDenominator(new Element\Identifier('a'));
+$fraction->setNumerator(new Element\Numeric(3));
+
+$math->add($fraction);
+```
diff --git a/docs/usage/elements/identifier.md 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
+<math display="block">
+  <mi>a</mi>
+</math>
+
+### XML
+``` xml
+<math display="block">
+  <mi>a</mi>
+</math>
+```
+
+### PHP
+
+``` php
+<?php
+
+use PhpOffice\Math\Element;
+use PhpOffice\Math\Math;
+
+$math = new Math();
+
+$identifier = new Element\Identifier('a');
+
+$math->add($identifier);
+```
diff --git a/docs/usage/elements/numeric.md 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
+<math display="block">
+  <mn>3</mn>
+</math>
+
+### XML
+``` xml
+<math display="block">
+  <mn>3</mn>
+</math>
+```
+
+### PHP
+
+``` php
+<?php
+
+use PhpOffice\Math\Element;
+use PhpOffice\Math\Math;
+
+$math = new Math();
+
+$identifier = new Element\Numeric(3);
+
+$math->add($identifier);
+```