From eba0a9640242176ab478ef020387ab0b587d1452 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9l=C3=A8ne=20Martin?= Date: Mon, 11 Mar 2024 16:03:26 -0700 Subject: [PATCH 1/5] Include project status and related work in readme --- README.rst | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index bf988ab9..09e5bed4 100644 --- a/README.rst +++ b/README.rst @@ -13,16 +13,27 @@ pyxform .. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/python/black -pyxform is a Python library that makes writing forms for ODK Collect and Enketo easy by converting XLSForms (Excel spreadsheets) into ODK XForms. The XLSForms format is used in a `number of tools `_. +``pyxform`` is a Python library that simplifies writing forms for ODK Collect and Enketo by converting spreadsheets that follow the `XLSForm standard `_ into `ODK XForms `_. The XLSForms format is used in a `number of tools `_. -XLS(X) documents used as input must follow to the `XLSForm standard `_ and the resulting output follows the `ODK XForms `_ standard. +Project status +=============== +``pyxform`` was started at the `Sustainable Engineering Lab at Columbia University `_ and was then maintained for many years primarily by `Ona `_. Since 2018, it has been maintained by the `ODK team `_ (primarily by `Lindsay Stevens `_). +Our current goals are: -pyxform is a major rewrite of `xls2xform `_. +* Enabling more complex workflows through sophisticated XPath expressions and `entities `_ +* Improving error messages and making troubleshooting easier +* Improving experience for multi-language forms + +Using ``pyxform`` +================== +For support, please start by posting to `the ODK forum `__ where your question will get the most visibility. + +Most users use `pyxform` through a form server, some using `the pyxform-http service wrapper `_. The command line utility can be helpful for troubleshooting or as part of a broader form creation pipeline. Running the latest release of pyxform -===================================== -For those who want to convert forms at the command line, the latest official release of pyxform can be installed using `pip `_:: +------------------------------------- +To convert forms at the command line, the latest official release of pyxform can be installed using `pip `_:: pip install pyxform @@ -33,7 +44,7 @@ The ``xls2xform`` command can then be used:: The currently supported Python versions for ``pyxform`` are 3.7, 3.8 and 3.9. Running pyxform from local source -================================= +--------------------------------- Note that you must uninstall any globally installed ``pyxform`` instance in order to use local modules. Please install java 8 or newer version. @@ -66,7 +77,7 @@ To leave and return to the virtualenv:: ~/repos/pyxform/venv/bin/xls2xform Installing pyxform from remote source -===================================== +------------------------------------- ``pip`` can install from the GitHub repository. Only do this if you want to install from the master branch, which is likely to have pre-release code. To install the latest release, see above.:: pip install git+https://github.com/XLSForm/pyxform.git@master#egg=pyxform @@ -92,6 +103,10 @@ Before committing, make sure to format and lint the code using ``ruff``:: If you are using a copy of ``ruff`` outside your virtualenv, make sure it is the same version as listed in ``pyproject.toml``. Use the project configuration for ``ruff` in ``pyproject.toml``, which occurs automatically if ``ruff`` is run from the project root (where ``pyproject.toml`` is). +Contributions +------------- +We welcome contributions that have a clearly-stated goal and are tightly focused. In general, successful contributions will first be discussed on `the ODK forum `__ or in an issue. We prefer discussion threads on the ODK forum because ``pyxform`` issues generally involve considerations for other tools and specifications in ODK and its broader ecosystem. Opening up an issue or a pull request directly may be appropriate if there is a clear bug or an issue that only affects ``pyxform`` developers. + Writing tests ------------- Make sure to include tests for the changes you're working on. When writing new tests you should add them in ``tests`` folder. Add to an existing test module, or create a new test module. Test modules are named after the corresponding source file, or if the tests concern many files then module name is the topic or feature under test. @@ -152,3 +167,9 @@ Releases are now automatic. These instructions are provided for forks or for a f flit --debug publish --no-use-vcs 6. Tag the GitHub release and publish it. + +Related projects +================ + +* `xls2xform `_: ``pyxform``'s precursor which was rewritten into the library we now know +* `YAML XLSForms `_: useful if you're looking to store XLSForms in version control or automatically format XLSForms From 13f67a57f41d64d3f7678f5d11ef1cc97e5bfc4d Mon Sep 17 00:00:00 2001 From: Lindsay Stevens Date: Wed, 13 Mar 2024 18:29:30 +1100 Subject: [PATCH 2/5] chg: rewording and add related projects --- README.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index 09e5bed4..81d421a6 100644 --- a/README.rst +++ b/README.rst @@ -17,19 +17,24 @@ pyxform Project status =============== -``pyxform`` was started at the `Sustainable Engineering Lab at Columbia University `_ and was then maintained for many years primarily by `Ona `_. Since 2018, it has been maintained by the `ODK team `_ (primarily by `Lindsay Stevens `_). +``pyxform`` is actively maintained by `ODK `_. -Our current goals are: +Current goals for the project include: -* Enabling more complex workflows through sophisticated XPath expressions and `entities `_ -* Improving error messages and making troubleshooting easier -* Improving experience for multi-language forms +* Enable more complex workflows through sophisticated XPath expressions and `entities `_ +* Improve error messages and making troubleshooting easier +* Improve experience, particularly for multi-language forms + +``pyxform`` was started at the `Sustainable Engineering Lab at Columbia University `_, and until 2018 was maintained primarily by `Ona `_. Using ``pyxform`` ================== -For support, please start by posting to `the ODK forum `__ where your question will get the most visibility. +For user support, please start by posting to `the ODK forum `__ where your question will get the most visibility. -Most users use `pyxform` through a form server, some using `the pyxform-http service wrapper `_. The command line utility can be helpful for troubleshooting or as part of a broader form creation pipeline. +There are 3 main ways that ``pyxform`` is used: +* Through a form server, such as the `pyxform-http service wrapper `_, or `ODK Central `_. +* The command line utility ``xls2xform``, which can be helpful for troubleshooting or as part of a broader form creation pipeline. +* As a library, meaning that another python project imports functionality from ``pyxform``. Running the latest release of pyxform ------------------------------------- @@ -171,5 +176,36 @@ Releases are now automatic. These instructions are provided for forks or for a f Related projects ================ -* `xls2xform `_: ``pyxform``'s precursor which was rewritten into the library we now know -* `YAML XLSForms `_: useful if you're looking to store XLSForms in version control or automatically format XLSForms +These projects are not vetted or endorsed but are linked here for reference. + +**Converters** +*To XLSForm* +* `cueform `_ (Go): from CUE +* `md2xlsform `_ (Python): from MarkDown +* `xlsform `_ (Python): from JSON +* `yxf `_ (Python): from YAML + +*From XLSForm* +* `ODK2Doc `_ (R): to Word +* `OdkGraph `_ (Python): to a graph +* `Pureser `_ (Swift): to HTML +* `ppp `_ (Python): to HTML, PDF, Word +* `QuestionnaireHTML `_ (R): to HTML +* `xlsform-converter `_ (Python): to Django modules +* `xlsform `_ (Python): to JSON +* `xlsform2json `_ (Java): to JSON +* `XLSform2PDF `_ (Python): to PDF +* `xlson `_ (Python): to OpenSRP JSON +* `yxf `_ (Python): to YAML + +**Management Tools** +* `surveydesignr `_ (R): compare XLSForms +* `ipacheckscto `_ (Stata): check XLSForm for errors or design issues +* `kobocruncher `_ (R): generate analysis Rmd from XLSForm +* `odkmeta `_ (Stata): use XLSForm to import ODK data to Stata +* `odktools _` (C++): convert pyxform internal data model to MySQL +* `pmix `_ (Python): manage XLSForm authoring +* `pyxform-docker `_ (Dockerfile): image for pyxform development +* `xform-test `_ (Java): test XLSForms +* `xlsformpo `_ (Python): use .po files for XLSForm translations +* `XlsFormUtil `_ (R): manage XLSForm authoring From 9116e5a403e21f59d59a4d97e94c2eb602173ba8 Mon Sep 17 00:00:00 2001 From: Lindsay Stevens Date: Wed, 13 Mar 2024 18:31:54 +1100 Subject: [PATCH 3/5] fix: formatting --- README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.rst b/README.rst index 81d421a6..aeb85fda 100644 --- a/README.rst +++ b/README.rst @@ -32,6 +32,7 @@ Using ``pyxform`` For user support, please start by posting to `the ODK forum `__ where your question will get the most visibility. There are 3 main ways that ``pyxform`` is used: + * Through a form server, such as the `pyxform-http service wrapper `_, or `ODK Central `_. * The command line utility ``xls2xform``, which can be helpful for troubleshooting or as part of a broader form creation pipeline. * As a library, meaning that another python project imports functionality from ``pyxform``. @@ -180,12 +181,14 @@ These projects are not vetted or endorsed but are linked here for reference. **Converters** *To XLSForm* + * `cueform `_ (Go): from CUE * `md2xlsform `_ (Python): from MarkDown * `xlsform `_ (Python): from JSON * `yxf `_ (Python): from YAML *From XLSForm* + * `ODK2Doc `_ (R): to Word * `OdkGraph `_ (Python): to a graph * `Pureser `_ (Swift): to HTML @@ -199,6 +202,7 @@ These projects are not vetted or endorsed but are linked here for reference. * `yxf `_ (Python): to YAML **Management Tools** + * `surveydesignr `_ (R): compare XLSForms * `ipacheckscto `_ (Stata): check XLSForm for errors or design issues * `kobocruncher `_ (R): generate analysis Rmd from XLSForm From 227268cc2bfe2f743923bfee787436403d7b8292 Mon Sep 17 00:00:00 2001 From: Lindsay Stevens Date: Wed, 13 Mar 2024 18:33:22 +1100 Subject: [PATCH 4/5] fix: formatting --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index aeb85fda..6f579288 100644 --- a/README.rst +++ b/README.rst @@ -180,6 +180,7 @@ Related projects These projects are not vetted or endorsed but are linked here for reference. **Converters** + *To XLSForm* * `cueform `_ (Go): from CUE @@ -207,7 +208,7 @@ These projects are not vetted or endorsed but are linked here for reference. * `ipacheckscto `_ (Stata): check XLSForm for errors or design issues * `kobocruncher `_ (R): generate analysis Rmd from XLSForm * `odkmeta `_ (Stata): use XLSForm to import ODK data to Stata -* `odktools _` (C++): convert pyxform internal data model to MySQL +* `odktools `_ (C++): convert pyxform internal data model to MySQL * `pmix `_ (Python): manage XLSForm authoring * `pyxform-docker `_ (Dockerfile): image for pyxform development * `xform-test `_ (Java): test XLSForms From caeb5dd780f2afcc6aff215cec18486002820920 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9l=C3=A8ne=20Martin?= Date: Thu, 14 Mar 2024 16:22:58 -0700 Subject: [PATCH 5/5] Use consistent tense --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 6f579288..2eb125c0 100644 --- a/README.rst +++ b/README.rst @@ -22,7 +22,7 @@ Project status Current goals for the project include: * Enable more complex workflows through sophisticated XPath expressions and `entities `_ -* Improve error messages and making troubleshooting easier +* Improve error messages and make troubleshooting easier * Improve experience, particularly for multi-language forms ``pyxform`` was started at the `Sustainable Engineering Lab at Columbia University `_, and until 2018 was maintained primarily by `Ona `_.