diff --git a/doc/index.rst b/doc/index.rst index 3fe932a..0924eed 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,12 +19,41 @@ Widgets ------- .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + :caption: Getting Started - widgets/actoranalysis - widgets/actionanalysis - widgets/settinganalysis + widgets/installation + widgets/usage + widgets/tutorials + widgets/knownissues + +.. toctree:: + :maxdepth: 2 + :caption: Widgets + + widgets/actions + widgets/actors + widgets/elements widgets/narrativenetwork + widgets/setting + +.. toctree:: + :maxdepth: 2 + :caption: Developers + + widgets/buildingfromsource + widgets/contribute + widgets/changelog + +.. toctree:: + :maxdepth: 2 + :caption: About + + widgets/contact + widgets/howtocite + widgets/inaction + widgets/faqs + Indices and tables ================== diff --git a/doc/widgets.json b/doc/widgets.json index f86e1c2..3179703 100644 --- a/doc/widgets.json +++ b/doc/widgets.json @@ -2,6 +2,21 @@ [ "Orange Story Navigator", [ + { + "text": "Installation", + "doc": "widgets/install.md", + "icon": "../orangecontrib/storynavigation/widgets/images/storynavigator_logo.png", + "background": "#C0FF97", + "keywords": ["install", "Orange", "installation","Add-on"] + }, + + { + "text": "Actions Analysis", + "doc": "widgets/actionanalysis.md", + "icon": "../orangecontrib/storynavigation/widgets/icons/action_analysis_icon.png", + "background": "#C0FF97", + "keywords": ["verb tense", "verbs", "actions", "part of speech tagging"] + }, { "text": "Actor Analysis", "doc": "widgets/actoranalysis.md", @@ -10,11 +25,18 @@ "keywords": ["part of speech tagging", "nouns", "characters", "actors"] }, { - "text": "Actions Analysis", - "doc": "widgets/actionanalysis.md", - "icon": "../orangecontrib/storynavigation/widgets/icons/action_analysis_icon.png", + "text": "Elements Analysis", + "doc": "widgets/elements.md", + "icon": "../orangecontrib/storynavigation/widgets/icons/tagger_icon.png", "background": "#C0FF97", - "keywords": ["verb tense", "verbs", "actions", "part of speech tagging"] + "keywords": ["NLP tagging", "Custom tagging", "actions", "actors"] + }, + { + "text": "Narrative Network", + "doc": "widgets/narrativenetwork.md", + "icon": "../orangecontrib/storynavigation/widgets/icons/narrative_network_icon.png", + "background": "#C0FF97", + "keywords": ["network analysis", "networks", "subject verb object tuples", "story units"] }, { "text": "Setting Analysis", @@ -22,13 +44,6 @@ "icon": "../orangecontrib/storynavigation/widgets/icons/setting_analysis_icon.svg", "background": "#C0FF97", "keywords": ["clustering", "tf-idf", "word embeddings"] - }, - { - "text": "Narrative Network", - "doc": "widgets/narrativenetwork.md", - "icon": "../orangecontrib/storynavigation/widgets/icons/narrative_network_icon.png", - "background": "#C0FF97", - "keywords": ["network analysis", "networks", "subject verb object tuples", "story units"] } ] ] diff --git a/doc/widgets/CODE_OF_CONDUCT.md b/doc/widgets/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..75077f2 --- /dev/null +++ b/doc/widgets/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +t.vroegh@esciencecenter.nl. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at +. diff --git a/doc/widgets/actionanalysis.md b/doc/widgets/actions.md similarity index 100% rename from doc/widgets/actionanalysis.md rename to doc/widgets/actions.md diff --git a/doc/widgets/actoranalysis.md b/doc/widgets/actors.md similarity index 100% rename from doc/widgets/actoranalysis.md rename to doc/widgets/actors.md diff --git a/doc/widgets/buildingfromsource.md b/doc/widgets/buildingfromsource.md new file mode 100644 index 0000000..06d2c65 --- /dev/null +++ b/doc/widgets/buildingfromsource.md @@ -0,0 +1,50 @@ +Building from source +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + +This section is for those who want to build the add-on from source and extend, customise, or fix bugs in it. +**Note:** Mac M1 (Apple silicon) users may encounter problems with building ``storynavigator`` using certain Python 3.8.x or 3.9.x versions and / or actually building or running these specific Python versions at all on your Mac. If you encounter such issues, it is recommended to install [Rosetta 2](https://osxdaily.com/2020/12/04/how-install-rosetta-2-apple-silicon-mac/) and always run the terminal using Rosetta 2 (see how to do the latter [here](https://www.courier.com/blog/tips-and-tricks-to-setup-your-apple-m1-for-development/)) for development tasks. + +Requirements: + +1. A tool for checking out a [Git](https://git-scm.com/) repository +2. Python 3.9.12+ + +Steps to build and test from source: + +1. Get a copy of the code + + ```git clone git@github.com:navigating-stories/orange-story-navigator.git``` + +2. Change into the ```orange-story-navigator/``` directory + + ```cd orange-story-navigator``` + +3. Create and activate a new Python virtual environment using [virtualenv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) + +4. Run the following command + + ```pip install -r requirements.txt``` + +5. If Step 4. completed with no errors, run this command + + ```pip install -e .``` + +> This command installs the widget and registers it with your Orange3 installation. If you encountered an error during Step 4, file an [issue](https://github.com/navigating-stories/orange-story-navigator/issues) with the details and skip the remaining steps. + +6. Run ```orange-canvas``` or ```python -m Orange.canvas``` + +The Orange3 application should shortly start up with a splash screen + +## Testing + +Run tests with `pytest`. + +For coverage: + +```python +coverage run -m pytest +coverage report +# or +coverage html +``` diff --git a/doc/widgets/changelog.md b/doc/widgets/changelog.md new file mode 100644 index 0000000..e94fece --- /dev/null +++ b/doc/widgets/changelog.md @@ -0,0 +1,8 @@ +Changelog +======= + +![](../../doc/widgets/images/storynavigator_logo_small.png) + +"Changelog": list of featured added, removed / amended in each version + +Coming soon! diff --git a/doc/widgets/contact.md b/doc/widgets/contact.md new file mode 100644 index 0000000..472eff5 --- /dev/null +++ b/doc/widgets/contact.md @@ -0,0 +1,41 @@ +Contact Information +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + + +The Story Navigator is maintained by the [Netherlands eScience Center](https://www.esciencecenter.nl/) in collaboration with the [Faculty of Behavioural, Management and Social Sciences (BMS)](https://www.utwente.nl/en/bms/) at the [University of Twente](https://www.utwente.nl/en/). If you have any questions, feedback, or need support, please feel free to reach out to us. Below are the primary contacts and useful links for your reference: + +**General Inquiries** + +For general questions and information, you can reach the Principal Investigator Prof. dr. Gerben J. Westerhof: +- **Email**: [g.j.westerhof@utwente.nl](mailto:g.j.westerhof@utwente.nl) +- **Phone**: +31.53.489.6074 +- **Website**: https://personen.utwente.nl/g.j.westerhof + +**Technical Support** + +For technical support and troubleshooting, please contact our Lead Research Software Engineer Kody Moodley or visit the Orange Data Mining website for additional resources: +- **Email**: [k.moodley@esciencecenter.nl](mailto:k.moodley@esciencecenter.nl) +- **Orange**: [https://orangedatamining.com/](https://orangedatamining.com/) +- **Documentation**: [https://orange-story-navigator.readthedocs.io/en/latest/](https://orange-story-navigator.readthedocs.io/en/latest/) + +**Collaboration** + +If you are interested in contributing, reach out at: +- **Email**: [info@esciencecenter.nl](mailto:info@esciencecenter.nl) +- **Github**: [https://github.com/navigating-stories/orange-story-navigator](mailto:https://github.com/navigating-stories/orange-story-navigator) + +**Follow Us** + +Stay updated on the project by following us on: +- **RSD**: [Research Software Directory](https://research-software-directory.org/projects/navigating-stories) +- **LinkedIn**: [https://www.linkedin.com/company/netherlands-escience-center/](https://www.linkedin.com/company/netherlands-escience-center/) +- **Homepage**: [https://navigating-stories.github.io/](https://navigating-stories.github.io/) +- **Story Lab**: [https://www.utwente.nl/en/bms/ehealth/research/story-lab/](https://www.utwente.nl/en/bms/ehealth/research/story-lab/) + + +For more detailed information, visit our [official website](https://www.esciencecenter.nl/). + +--- + +Thank you for your interest and support. We look forward to assisting you! \ No newline at end of file diff --git a/doc/widgets/contribute.md b/doc/widgets/contribute.md new file mode 100644 index 0000000..acd658b --- /dev/null +++ b/doc/widgets/contribute.md @@ -0,0 +1,111 @@ +Contribute +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + +This section is for those who want to contribute to the Story Navigator add-on by building from source, extending, customizing, or fixing bugs in it. + +# Contributing guidelines + +Welcome! *Story Navigator* is an open-source project that helps analyzing textual stories using the lenses of narrative psychology, narrative analysis, and narrative theory. We aim to work with a a wide range of textual data. If you're trying *Story Navigator* with your data, your experience, questions, bugs you encountered, and suggestions for improvement are important to the success of the project. + +We have a [Code of Conduct](https://github.com/navigating-stories/orange-story-navigator/tree/documentation/doc/widgets/CODE_OF_CONDUCT.md), please follow it in all your interactions with the project. + +## Questions, feedback, bugs + +Use the search function to see if someone else already ran accross the same issue. Feel free to open a new [issue here](https://github.com/navigating-stories/orange-story-navigator/issues) to ask a question, suggest improvements/new features, or report any bugs that you ran into. + +## Submitting changes + +Even better than a good bug report is a fix for the bug or the implementation of a new feature. We welcome any contributions that help improve the code. + +When contributing to this repository, please first discuss the change you wish to make via an [issue](https://github.com/navigating-stories/orange-story-navigator/issues) with the owners of this repository before making a change. You can also contact the developers at developers@storynavigator.com before submitting PRs. + +Contributions can come in the form of: + +- Bug fixes +- New features +- Improvement of existing code +- Updates to the documentation +- Etc + +We use the usual GitHub pull-request flow. For more info see [GitHub's own documentation](https://help.github.com/articles/using-pull-requests/). + +Typically this means: + +1. [Forking](https://docs.github.com/articles/about-forks) the repository and/or make a [new branch](https://docs.github.com/articles/about-branches) +2. Making your changes +3. Make sure that the tests pass and add your own +4. Make sure the documentation is updated for new features +5. Pushing the code back to Github +6. [Create a new Pull Request](https://help.github.com/articles/creating-a-pull-request/) + +One of the code owners will review your code and request changes if needed. Once your changes have been approved, your contributions will become part of *Story Navigator*. + +## Getting started with development + +### Setup + +*Story Navigator* targets Python 3.9.12 or newer. + +Clone the repository into the `storynavigator` directory: + +```console +git clone https://github.com/navigating-stories/orange-story-navigator +``` + +Install using `virtualenv`: + +```console +cd storynavigator +python3 -m venv env +source env/bin/activate +python3 -m pip install -e .[develop] +``` + +Alternatively, install using Conda: + +```console +cd storynavigator +conda create -n storynavigator python=3.10 +conda activate storynavigator +pip install -e .[develop] +``` + +### Running tests + +*Story Navigator* uses [pytest](https://docs.pytest.org/en/latest/) to run the tests. You can run the tests for yourself using: + +```console +pytest +``` + +To check coverage: + +```console +coverage run -m pytest +coverage report # to output to terminal +coverage html # to generate html report +``` + +### Building the documentation + +The documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/), and uses [mkdocs](https://www.mkdocs.org/) to generate the pages. + +To build the documentation for yourself: + +```console +pip install -e .[docs] +mkdocs serve +``` + +You can find the documentation source in the [docs](https://github.com/navigating-stories/orange-story-navigator/tree/master/doc) directory. + +### Making a release + +1. Make a new [release](https://github.com/navigating-stories/orange-story-navigator/releases). + +2. Under 'Choose a tag', set the tag to the new version. The versioning scheme we use is [SemVer](http://semver.org/), so bump the version (*major*/*minor*/*patch*) as needed. + +3. The [upload to pypi](https://pypi.org/project/orange-story-navigator/) is triggered when a release is published and handled by [this workflow](https://github.com/navigating-stories/orange-story-navigator/actions/workflows/publish.yaml). + +4. The [upload to zenodo](https://zenodo.org/records/10994947) is triggered when a release is published. diff --git a/doc/widgets/faqs.md b/doc/widgets/faqs.md new file mode 100644 index 0000000..ec541bd --- /dev/null +++ b/doc/widgets/faqs.md @@ -0,0 +1,7 @@ +FAQ's +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + +FAQs: frequently asked questions about SN with their answers. E.g., where can I find information about how to...? + +Coming soon! diff --git a/doc/widgets/howtocite.md b/doc/widgets/howtocite.md new file mode 100644 index 0000000..a11a8b7 --- /dev/null +++ b/doc/widgets/howtocite.md @@ -0,0 +1,70 @@ +How to cite Story Navigator +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + + +If you use this software in your work, please cite it using the following metadata [(Learn more about CITATION files).](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) + +You can do this easily with one of these options: + +- The 'cite this repository' menu in the right tab at https://github.com/navigating-stories/orange-story-navigator. +- The [citation file](CITATION.cff). #TODO: cff file in repo (see below) +- If you prefer to copypaste, here you have the APA and BibTex strings: + +**APA**: Moodley, K. Hafner, F., Lüken, M., Tjong Kim Sang, E. Smeets, S. & Vroegh, T. (2024). orange-story-navigator (Version 0.0.19) [Computer software]. https://github.com/navigating-stories/orange-story-navigator + +**BibTex**: @software{orange-story-navigator, + author = {Moodley, Kody, Hafner, Flavio, Lüken, Malte, Tjong Kim Sang, Erik, Smeets, Stef. and Vroegh, Thijs}, + title = {orange-story-navigator (Version 0.0.19) [Computer software]}, + url = {https://github.com/navigating-stories/orange-story-navigator} + +----------------------------------------------- +cff-version: 1.2.0 +title: Unraphael +message: >- + If you use this software, please cite it using the + metadata from this file. +type: software +authors: + - given-names: Kody + family-names: Moodley + affiliation: Netherlands eScience Center + orcid: 'https://orcid.org/0000-0001-5666-1658' + - given-names: Flavio + family-names: Hafner + affiliation: Netherlands eScience Center + orcid: 'TODO: add ORCID' + - given-names: Malte + family-names: Lüken + affiliation: Netherlands eScience Center + orcid: 'https://orcid.org/0000-0001-7095-203X' + - given-names: Erik + family-names: Tjong Kim Sang + affiliation: Netherlands eScience Center + orcid: 'https://orcid.org/0000-0002-8431-081X' + - given-names: Stef + family-names: Smeets + affiliation: Netherlands eScience Center + orcid: 'https://orcid.org/0000-0001-5107-3531' + - given-names: Thijs + family-names: Vroegh + affiliation: Netherlands eScience Center + orcid: 'https://orcid.org/0000-0002-6311-0798' + +repository-code: 'https://github.com/navigating-stories' +url: 'https://orange-story-navigator.readthedocs.io/en/latest/' +abstract: >- + add-on for the Orange3 data mining platform which is able to analyse Dutch textual stories using the lenses of narrative psychology, narrative analysis, and narrative theory +keywords: + - stories + - text mining + - storytelling + - data analysis + - orange3 +identifiers: + - type: doi + value: 10.5281/zenodo.10994947 +license: GPL-3.0 +version: 0.0.19 + +----------------------------------------------- diff --git a/doc/widgets/images/storynavigator_logo_small.png b/doc/widgets/images/storynavigator_logo_small.png new file mode 100644 index 0000000..d33c0dc Binary files /dev/null and b/doc/widgets/images/storynavigator_logo_small.png differ diff --git a/doc/widgets/inaction.md b/doc/widgets/inaction.md new file mode 100644 index 0000000..6a53cea --- /dev/null +++ b/doc/widgets/inaction.md @@ -0,0 +1,13 @@ +In action +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + +This section includes links to projects, events, papers, blogposts, videos, etc. which mention or make use of StoryNavigator. + +**Blogs** + +[The Orange3 data mining platform for the Social Sciences and Humanities](https://blog.esciencecenter.nl/the-orange3-data-mining-platform-as-a-research-tool-2167336a5c0d) + + + +More coming soon! diff --git a/doc/widgets/install.md b/doc/widgets/installation.md similarity index 93% rename from doc/widgets/install.md rename to doc/widgets/installation.md index 9fa8a57..1718138 100644 --- a/doc/widgets/install.md +++ b/doc/widgets/installation.md @@ -1,6 +1,6 @@ -How to enable StoryNavigator in Orange +Installation ======= -![](../../doc/widgets/images/storynavigator_logo.png) +![](../../doc/widgets/images/storynavigator_logo_small.png) To install the Orange3 StoryNavigator Add-on, use the following steps. diff --git a/doc/widgets/knownissues.md b/doc/widgets/knownissues.md new file mode 100644 index 0000000..236db29 --- /dev/null +++ b/doc/widgets/knownissues.md @@ -0,0 +1,20 @@ +Known issues +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + +Known issues: runtime issues that users might experience (with workarounds if available) and misconceptions about how SN works or what it is supposed to do. The following is a list of known issues as part of working with the Orange3 StoryNavigator Add-on: + +**1** + +..... + + +**2** + +...... + +**3** + +...... + +**This list of issues can be further updated in the future.** \ No newline at end of file diff --git a/doc/widgets/narrativenetwork.md b/doc/widgets/narrativenetwork.md index 91c2efd..b16500d 100644 --- a/doc/widgets/narrativenetwork.md +++ b/doc/widgets/narrativenetwork.md @@ -1,4 +1,4 @@ -Narrative Network +Narrative network ================= ![](../../orangecontrib/storynavigation/widgets/icons/narrative_network_icon.png) diff --git a/doc/widgets/settinganalysis.md b/doc/widgets/setting.md similarity index 100% rename from doc/widgets/settinganalysis.md rename to doc/widgets/setting.md diff --git a/doc/widgets/tutorials.md b/doc/widgets/tutorials.md new file mode 100644 index 0000000..b3ec68e --- /dev/null +++ b/doc/widgets/tutorials.md @@ -0,0 +1,6 @@ +Tutorials +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + +"Tutorials" will provide video tutorials with workflows that connect the widgets in order to answer some predefined research questions. + diff --git a/doc/widgets/usage.md b/doc/widgets/usage.md new file mode 100644 index 0000000..be1bc28 --- /dev/null +++ b/doc/widgets/usage.md @@ -0,0 +1,7 @@ +Usage +======= +![](../../doc/widgets/images/storynavigator_logo_small.png) + +"Usage" will show how to use each widget. + +Coming soon!