diff --git a/README.rst b/README.rst index bf988ab9..2eb125c0 100644 --- a/README.rst +++ b/README.rst @@ -13,16 +13,33 @@ 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`` is actively maintained by `ODK `_. +Current goals for the project include: -pyxform is a major rewrite of `xls2xform `_. +* Enable more complex workflows through sophisticated XPath expressions and `entities `_ +* 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 `_. + +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``. 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 +50,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 +83,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 +109,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 +173,44 @@ 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 +================ + +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