README.rst

OXID eShop developer documentation

This is the OXID eShop developer documentation.

The generated documentation can be found here: https://docs.oxid-esales.com/developer/en/7.0-rc.2/

If you want to contribute, please read https://docs.oxid-esales.com/developer/en/7.0-rc.2/index.html#help-improving-this-documentation. Generate the documentation locally in order to test your changes as described in the following section.

Generating docs locally

To generate documentation locally, our SDK with preconfigured Sphinx container can be used. Please refer to SDK README file Sphinx usage section.

The Old way:

1. Install sphinx.

2. Install the sphinx_rtd_theme (if it is missing).

3. Install the PHP highlighting extensions.

4. Install the plantuml extension.

   If you have a mac PC, install plantuml separately e.g. via brew.

   Either configure the path to the file plantuml.jar in the file config.py or put a wrapper script in your path as described in the link above.

5. Clone thw documentation repository:

   git clone https://github.com/OXID-eSales/developer_documentation.git

6. To generate documentation, run:

   cd developer_documentation
   sphinx-build ./ ./build

7. Open build/index.html file with your browser.

Generating diagrams

To generate diagrams using plantUml, use this command:

java -jar /opt/plantuml.jar -svg -o ./ **.puml

/opt/plantuml.jar - path to your plantUml file.

PlantUml will generate .svg files, which can be used in documentation.

Using OXID SDK for regenerating the documentation

By being in the root of the project (where Makefile is), install the documentation and required containers by using following commands:

git clone https://github.com/OXID-eSales/developer_documentation docs
make addsphinxservice docpath='./docs'
docker-compose up --build -d sphinx

To run documentation regeneration, use:

make generate-docs

Generated documentation will be available in docs/build folder