From 7512c03178b4a56ab81a08f3b1b48958f49082fc Mon Sep 17 00:00:00 2001 From: Marc Jansen Date: Fri, 26 May 2023 12:23:59 +0200 Subject: [PATCH] docs: split content of README.md into dedicated files --- CONTRIBUTING.md | 2 + DEVELOPING.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 109 ++-------------------------------------------- 3 files changed, 118 insertions(+), 105 deletions(-) create mode 100644 DEVELOPING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba8aaf899..4acdc4713 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,8 @@ Thank you for contributing to our project! We are happy for any kind of contribution and welcome anyone who is interested in doing so. Please also have a look at our [code of conduct](./CODE_OF_CONDUCT.md). +If you are looking for the more detailed developer guide, you can find it in [`DEVELOPING.md`](./DEVELOPING.md). + ## Contributions other than code There is more than one way of contributing. If you have questions, topics to discuss or anything else diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 000000000..27bfe46d2 --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,112 @@ +# Developer Guide + +Thank you for taking the time to read the following hints for developers! + +Make sure to read the general [guidelines for contributions](./CONTRIBUTING.md) and our [code of conduct](./CODE_OF_CONDUCT.md). + +## Developing GeoStyler UI Components + +The easiest way to develop UI components is to use `styleguidist`. Just run `npm run styleguide` and the interactive documenation will be running on `http://localhost:6060`. + +For more complex developments such as integrations with different parsers, it might be helpful to `npm link` your local repository to the GeoStyler Demo. If you include your component into one of our high-level components, you will be able to directly see the new components in your browser. To do so, follow these steps: + +```bash +git clone https://github.com/geostyler/geostyler.git +cd geostyler +npm i +npm link +npm run build + +cd .. +git clone https://github.com/geostyler/geostyler-demo.git +cd geostyler-demo +npm i +npm link geostyler +``` + +When working with npm link it may happen that some tools like webpack or typescript don't know how to resolve packages that are used in both packages (in this case `geostyler` and `geostyler-style`). So we have to configure this in the `geostyler-demo`: + +Replace `rootDir` with `rootDirs` and add the linked packages to the `rootDirs` in `tsconfig.json`. If you link some parsers too just add them as well. + +```diff +--- a/tsconfig.json ++++ b/tsconfig.json +@@ -9,9 +9,12 @@ + "allowJs": true, + "jsx": "react", + "moduleResolution": "node", +- "rootDir": ".", + "rootDirs": [ +- "./src/" ++ "./src/", ++ "../geostyler", + ], + "forceConsistentCasingInFileNames": true, + "noImplicitReturns": true, +``` + +Then uncomment or add resolve aliases to the webpack config: + +```diff +--- a/config/webpack.common.config.js ++++ b/config/webpack.common.config.js +@@ -35,7 +35,9 @@ module.exports = { + }, + alias: { + react: require.resolve('react'), +- 'geostyler-style': path.resolve('node_modules', 'geostyler-style') ++ 'geostyler-style': path.resolve('node_modules', 'geostyler-style'), ++ 'geostyler-sld-parser': path.resolve('node_modules', 'geostyler-sld-parser'), ++ 'antd': path.resolve('node_modules', 'antd') + } + }, + output: { +``` + +``` +npm run start +``` + +The GeoStyler Demo will then be served on `localhost:3000`. When doing changes to GeoStyler you have to rebuild the project via one of the following commands: + +```bash +npm run build +npm run build-dist +``` +Changes will automatically be updated in the browser. Please also provide tests and a minimal code example as \.example.md, if you add a new component, so the api documentation will always be up to date and other users can benefit from your work. + +## Troubleshooting +`Invalid hook call` error: +If the demo does not start but shows the above error, it means that `geostyler-demo` and `geostyler` are using different react sources. Please make sure to have the react alias in the `webpack.common.config.js` configured correctly. + +If there is an issue with a UI component, you may need to do the same for the `antd` module and add the alias. + +## Developing GeoStyler Style Parsers + +If you want to write your own style parser please take a look at the existing parsers for a consistent project setup. Developing them is a straighforward task, but don't forget: **style parsers have to implement the [GeoStyler Style interface](https://github.com/geostyler/geostyler-style).** + +If you want to work on an existing parser, do following steps to setup the project: + +```bash +git clone +cd +npm i +``` + +Parsers can be directly tested within their repositories, respectively. The best way to integrate your local changes into the UI/Demo is using `npm link`. +Run + +```bash +npm link +``` +from within your style parser repo and + +```bash +npm link +``` + +from within the GeoStyler Demo. + +## Developing GeoStyler Data Parsers + +Developing GeoStyler data parsers follows the same pattern as described in [Developing GeoStyler Style Parser](#Developing-GeoStyler-Style-Parsers), but keep in mind that **data parsers have to implement the [GeoStyler Data interface](https://github.com/geostyler/geostyler-data).** diff --git a/README.md b/README.md index 3de075c93..e2d48f27e 100644 --- a/README.md +++ b/README.md @@ -137,114 +137,13 @@ Compare the list of existing parsers below. ## Developer Guide -For our guidelines for contributions, please take a look at [CONTRIBUTING.md](./CONTRIBUTING.md). +For our guidelines for contributions, please take a look at [`CONTRIBUTING.md`](./CONTRIBUTING.md). Head there if you need general advice for first contributing steps (code or documentation). -### Developing GeoStyler UI Components +More detailed information to ensure a great development experience when working on geostyler is summarized in [`DEVELOPING.md`](./DEVELOPING.md). You'll find hints with regard to developing UI components or guidance when you want to enhance (or create) parsers for style formats or data formats there. -The easiest way to develop UI components is to use `styleguidist`. Just run `npm run styleguide` and the interactive documenation will be running on `http://localhost:6060`. +Additionally, please read through our [code of conduct](./CODE_OF_CONDUCT.md). -For more complex developments such as integrations with different parsers, it might be helpful to `npm link` your local repository to the GeoStyler Demo. If you include your component into one of our high-level components, you will be able to directly see the new components in your browser. To do so, follow these steps: - -```bash -git clone https://github.com/geostyler/geostyler.git -cd geostyler -npm i -npm link -npm run build - -cd .. -git clone https://github.com/geostyler/geostyler-demo.git -cd geostyler-demo -npm i -npm link geostyler -``` - -When working with npm link it may happen that some tools like webpack or typescript don't know how to resolve packages that are used in both packages (in this case `geostyler` and `geostyler-style`). So we have to configure this in the `geostyler-demo`: - -Replace `rootDir` with `rootDirs` and add the linked packages to the `rootDirs` in `tsconfig.json`. If you link some parsers too just add them as well. - -```diff ---- a/tsconfig.json -+++ b/tsconfig.json -@@ -9,9 +9,12 @@ - "allowJs": true, - "jsx": "react", - "moduleResolution": "node", -- "rootDir": ".", - "rootDirs": [ -- "./src/" -+ "./src/", -+ "../geostyler", - ], - "forceConsistentCasingInFileNames": true, - "noImplicitReturns": true, -``` - -Then uncomment or add resolve aliases to the webpack config: - -```diff ---- a/config/webpack.common.config.js -+++ b/config/webpack.common.config.js -@@ -35,7 +35,9 @@ module.exports = { - }, - alias: { - react: require.resolve('react'), -- 'geostyler-style': path.resolve('node_modules', 'geostyler-style') -+ 'geostyler-style': path.resolve('node_modules', 'geostyler-style'), -+ 'geostyler-sld-parser': path.resolve('node_modules', 'geostyler-sld-parser'), -+ 'antd': path.resolve('node_modules', 'antd') - } - }, - output: { -``` - - -``` -npm run start -``` - -The GeoStyler Demo will then be served on `localhost:3000`. When doing changes to GeoStyler you have to rebuild the project via one of the following commands: - -```bash -npm run build -npm run build-dist -``` -Changes will automatically be updated in the browser. Please also provide tests and a minimal code example as \.example.md, if you add a new component, so the api documentation will always be up to date and other users can benefit from your work. - -### Troubleshooting -`Invalid hook call` error: -If the demo does not start but shows the above error, it means that `geostyler-demo` and `geostyler` are using different react sources. Please make sure to have the react alias in the `webpack.common.config.js` configured correctly. - -If there is an issue with a UI component, you may need to do the same for the `antd` module and add the alias. - -### Developing GeoStyler Style Parsers - -If you want to write your own style parser please take a look at the existing parsers for a consistent project setup. Developing them is a straighforward task, but don't forget: **style parsers have to implement the [GeoStyler Style interface](https://github.com/geostyler/geostyler-style).** - -If you want to work on an existing parser, do following steps to setup the project: - -```bash -git clone -cd -npm i -``` - -Parsers can be directly tested within their repositories, respectively. The best way to integrate your local changes into the UI/Demo is using `npm link`. -Run - -```bash -npm link -``` -from within your style parser repo and - -```bash -npm link -``` - -from within the GeoStyler Demo. -### Developing GeoStyler Data Parsers - -Developing GeoStyler data parsers follows the same pattern as described in [Developing GeoStyler Style Parser](#Developing-GeoStyler-Style-Parsers), but keep in mind that **data parsers have to implement the [GeoStyler Data interface](https://github.com/geostyler/geostyler-data).** +We look forward to seeing you contribute soon! ## License