deploy: 4bc9da6

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: ecf811e7ee50f86fc0ffaf7e3200da00
+tags: 645f666f9bcd5a90fca523b33c5a78b7

CNAME

@@ -0,0 +1 @@
+wildbook.docs.wildme.org

_sources/contribute/code-guide.md

@@ -0,0 +1,167 @@
+# Code Contribition Guideline
+
+## General
+* DRY Principle: Do Not Repeat Yourself. Avoid code duplication by reusing components, functions, and styles. This not only minimizes the codebase but also simplifies maintenance and updates.
+* If you are adding code that will be custom to a single platform, the feature needs to be approved by the Wild Me team. If approved, add all custom code in a block at the bottom of the page to prevent merge conflicts.
+
+### Dependencies
+* All dependencies must be on a locked version. We do not accept PRs that use the `latest` version of anything.
+* We use dependabot for dependency management; however, due to inconsistencies in semantic versioning and behavioral changes in packages supporting machine learning, we do system testing for all PRs suggested by dependabot. If you want to update or add a new dependency, contact the Wild Me team to discuss the changes before submitting a PR. 
+
+### In-line styling
+Generally speaking, we want to avoid in-line styling to allow for greater consistency and understandability. If you have concerns with what theme styling to use, check the theme figma.
+
+### Internationalization
+All Wild Me tools are intended for an international audience, so we want to provide translated versions. An active goal for 2024 is to get ensure that all product copy has been internationalized according to the following standard.
+
+At present, in Wildbook, all copy except for site name, notification messages, and species names are wrapped and localized to 4 languages: German, English, French, Spanish, and Italian. Language files differ in location based on whether you are contributing to a react or jsp page. For all language updates, make sure that the update is addressed across all locales.
+
+#### React
+Language files are located in `frontend/src/locale/`. If you are adding a new string to the system, make sure the string is available across the different languages by adding the key and translated string to 
+* `de.json` - German
+* `en.json` - English
+* `es.json` - Spanish
+* `fr.json` - French
+* `it.json` - Italian
+Ensure that the key is all caps with underscores as separators and is human-legible. Ex: **THISKEY_IS_GOOD** vs this.key.NeedsToBe-fixed vs TKNTBF
+
+#### Jsp
+`.properties` files in the `resources/bundles` language folders are used to generate translations for different supported languages. If you add a new string to the system, add the string to the appropriate `.properties` file, and make sure the string is available across `en`, `de`, `es`, `fr`, and `it`. Either provide the English string in all files, or provide the translated string in each one.
+
+## Wildbook
+Presently, Wildbook is a tomcat application leveraging jsp as the frontend. We are transitioning to a react frontend with a standardized REST API framework. We are iteratively removing jsp pages. For more details on the trajectory of page updates, see the roadmap.
+
+### Variable naming conventions
+* Camel case
+* Don’t use single-letter variable names (no matter how temporary you think the code is)
+* Code should be clear enough to speak for itself without comments, but use your judgement on if a comment is necessary
+* Code for clarity rather than for efficiency (one-liners are cool, but not at the expense of future obfuscation)
+
+### Notes during modernization
+Because we are transitioning between tech stacks, there are some places where code is weird or where duplicate effort is necessary to maintain user experience.
+* If updating the header, you will need to update:
+  * `header.jsp`
+  * `header.jsx`
+  * `servletResponseTemplate.htm`
+* If changing a dropdown in a .jsp page, use the library `select 2`. It provides a single line component update that adds in the ability to filter the dropdown. For example: `$('#selectCode').select2({width: '100%'});`
+
+### React
+#### Plugins used
+* `eslint-plugin-react`: For React best practices.
+* `eslint-plugin-react-hooks`: Ensures correct use of hooks.
+
+#### Relevant rules
+* Semicolons are required ("semi": 2).
+* JSX is allowed in both .js and .jsx files ("react/jsx-filename-extension": 0).
+* Console statements show warnings ("no-console": 1).
+* React Hooks rules are enforced ("react-hooks/rules-of-hooks": "error").
+
+#### Best practices
+* _Prefer Bootstrap Classes_: Always use Bootstrap's utility classes for styling when possible. This ensures consistency across the project and leverages Bootstrap's responsive features. Only use custom CSS or inline styles when the desired styling cannot be achieved with Bootstrap.
+* _Code Consistency_: We are using eslint and prettier to enforce a consistent coding style throughout the project. This includes consistent naming conventions, file and folder structure, and code formatting.
+* _Componentization_: Break down the UI into reusable components to maximize code reusability and clarity. Each component should have a well-defined purpose and should operate independently as much as possible.
+* _State Management_: Carefully manage state to avoid unnecessary re-renders. Use local state (with `useState`) for data that affects only one component, and consider using context or state management libraries (like Redux or MobX) for shared state across many components.
+* _UseEffect Best Practices_: When using `useEffect`, always include all dependencies in the dependency array to avoid bugs related to stale state and props. Also, be sure to return a cleanup function to avoid memory leaks, especially when subscribing to external data sources.
+* _Props Validation_: Use `PropTypes` to validate props passed to a component, or consider using TypeScript for static type checking throughout the application. This can prevent many runtime errors and improve developer productivity.
+
+#### Tip and Tricks
+* If bootstrap components are stubbornly refusing to change color, try `accent-color`.
+
+#### Customizing copy
+If you are updating a translation for general use, do your PR against the `main` branch. If you are updating a language file to have specific copy associated with a specific platform, do your PR against the specific platform's branch.
+
+### Java/jsp style
+* Initialize variables and type signatures at the abstract/interface level when possible.
+
+Instead of:
+
+```
+ArrayList encounters = new ArrayList<Encounter>();
+...
+public int getMax(ArrayList<int> numbers) {
+```
+
+Try:
+
+```
+List encounters = new ArrayList<Encounter>();
+...
+public int getMax(Collection<int> numbers) {
+```
+
+It’s easier to read and more intuitive for a function to take a Map or List than a HashMap or ArrayList.
+
+The List interface defines how we want that variable to behave, and whether it’s an ArrayList or LinkedList is incidental. Keeping the variable and method signatures abstract means we can change the implementation later (eg swapping ArrayList->LinkedList) without changing the rest of our code.
+https://stackoverflow.com/questions/2279030/type-list-vs-type-arraylist-in-java
+
+Related: when writing utility methods, making the input type as abstract as possible makes the method versatile. See Util.asSortedList in Wildbook: since the input is an abstract Collection, it can accept a List, Set, PriorityQueue, or Vector as input, and return a sorted List.
+
+* Runtime (not style): Use Sets (not Lists or arrays) if you’re only keeping track of collection membership / item uniqueness. 
+
+Instead of:
+
+```
+    	List<MarkedIndividual> uniqueIndividuals = new ArrayList<MarkedIndividual>();
+    	for(Encounter currentEncounter: encounters){
+		MarkedIndividual currentInd = enc.getIndividual();
+		if !(uniqueIndividuals.contains(currentInd) {
+			uniqueIndividuals.add(currentInd);
+			doStuff();
+```
+      			
+Try:
+
+```
+Set<MarkedIndividual> uniqueIndividuals = new HashSet<MarkedIndividual>();	
+    	for(Encounter currentEncounter: encounters){
+		MarkedIndividual currentInd = enc.getIndividual();
+		if !(uniqueIndividuals.contains(currentInd) {
+			uniqueIndividuals.add(currentInd);
+			doStuff();
+```
+
+The reason is a little deep in the data types. Sets are defined as unordered collections of unique elements; and Lists/arrays are ordered collections with no bearing on element-uniqueness. If the order of a collection doesn’t matter and you’re just checking membership, you’ll have faster runtime using a Set.
+
+Sets implement contains, add, and remove methods much faster than lists [contains is O(log(n)) vs O(n) runtime]. A list has to iterate through the entire list every time it runs contains (it checks each item once at a time) while a set (especially a HashSet) keeps track of an item index for quick lookup.
+
+* Use for-each loops aka “enhanced for loops” to make loops more concise and readable.
+
+Instead of:
+
+```
+for (int i=0; i<encounters.length(); i++) {
+	Encounter enc = encounters.get(i)
+	doStuff();
+```
+
+try:
+
+```
+for (Encounter enc: encounters) {
+	doStuff();
+```
+
+Note that in both cases you might want to check if `encounters == null` if relevant, but you rarely need to check if `encounters.length()>0` because the for-loops take care of that.
+
+Conversely, if you want access to the `i` variable for logging or otherwise, the classic for-loop is best.
+
+
+* `Util.stringExists` is shorthand for a common string check:
+
+Instead of:
+
+```
+	if (str!=Null && !str.equals("")) {
+		doStuff();
+```
+
+Try:
+
+```
+	if (Util.stringExists(str)) {
+		doStuff();
+```
+
+This method also checks for the strings “none” and “unknown” which have given us trouble in displays in the past.
+
+* When dealing with any functionality that handles data persistence, make sure to use try catch exceptions. Data loss is considered a critical failure and an emergency to address.

_sources/contribute/copy-guide.md

@@ -0,0 +1,35 @@
+# Copy Contribution Guide
+
+We have specific standards for copy in the interface. These standards are more strictly adhered to in new react pages, but jsp pages should move towards these standard when edited.
+
+- Headers and field labels are title case. Descriptions and field placeholders are sentence case. ![](../assets/images/copy-example.png)
+- If a description is relevant to the component (ex: the dropdown is multi-select) rather than the specific field (ex: the search field looks through multiple database fields), incorporate the description into the component.
+- If a description is 1-2 sentences, do not finish with punctuation. If a description is longer than 2 sentences, finish with punctuation. Treat as a block in the UI.
+- Be mindful of character encoding.
+
+## Terminology
+We have learned that some terms are more intuitive than others and are working to update throughout the interface. The following list provides explanations of the terms used and any potential synonyms that may need to be adjusted.
+
+- Encounter: one animal at a specific time and location. This is the base object of the platform.
+- Sighting: one or more animals at a specific time and location. The object is made of one or more encounters linked together by a common time and place. _Potential synonyms: Occurrence_
+- Individual: one animal that is known and named. The object is made of one or more encounters linked together by a common understanding of identity. _Potential synonyms: Marked Individual_
+- Annotation: a box around the animal in the image. This is used during the matching process to avoid matching based off the background of the image.
+- MediaAsset: general term for images or videos that have been uploaded to the system. _Potential synonyms: photographs, fotography, video_
+- Location ID: location pulled from a user-defined list, used to filter data for algorithmic matching and for search. _Potential synonyms: locationID, region, study site_
+
+## Internationalization
+Currently, Wildbook supports 5 languages: English, French, German, Italian, and Spanish. Any new copy should be internationalized rather than added directly to the page.
+- Good examples: `/src/main/webapp/index.jsp`, `/frontend/src/pages/EncounterSearch.jsx`
+- Needs update: `/src/main/webapp/overview.jsp`
+
+To add copy for a react page:
+1. Navigate to `/frontend/src/locale`
+2. In each of the `.json` files, add the same reference tag.
+    - Try to group tags by page
+    - If using a common component, check to see if an existing label works for your field. Only use the same field if the context is the same (ex: all Location ID dropdowns can use the same field label).
+3. Provide translated copy for the reference tag in each language file.
+
+To add copy for a jsp page:
+1. Navigate to `/src/main/resources/bundles`
+2. In each of the locale folders, find the appropriate `.properties` file, add the same reference tag.
+3. Provide translated copy for the reference tag in each language file.

_sources/contribute/dev-setup.md

@@ -0,0 +1,78 @@
+# Dev Environment Setup
+
+## Prereqs
+You need the following installed on your system:
+* `default-jdk`
+* `build-essential`
+* `maven`
+* `npm`
+* `node` (minimum version: 18)
+* `docker-compose`
+
+## System setup
+1. Run `sudo sysctl -w vm.max_map_count=262144` (A requirement for OpenSearch, it only needs to be run once on your system.)
+1. Run `npm install react-app-rewired`
+1. `git clone` your [forked Wildbook repo](pr-workflow.md#fork-wildbook) (referred to as the **code directory** going forward)
+
+### Code directory setup
+1. In `devops/development/`, create a `.env` file with a copy the contents of `_env.template`. By default, no changes should be needed.
+1. `cd` to the root of the code directory
+1. run `npm install`
+1. run `chmod +x .husky/pre-commit` to enable husky linting
+1. `cd /frontend`
+1. run `npm install` to install all dependencies
+1. create a `.env` for React environment variables.
+    1. Add the public URL: `PUBLIC_URL= /react/`
+    1. Add the site name: `SITE_NAME=My Local Wildbook`
+
+### Deploy directory setup
+1. Create your **deploy directory**, matching the value of `WILDBOOK_BASE_DIR` in the .env file. The default is `~/wildbook-dev/`)
+1. Create the necessary subdirectories
+```
+wildbook-dev
+|--logs
+|--webapps
+   |--wildbook
+```
+
+### Build war file
+To run Wildbook in the development docker environment, even to try out the software, you need a "war file" which is made by compiling the Wildbook java project.
+
+To create the war file:
+1. `cd` to the root of the code directory
+1. Build your war file with `mvn clean install`
+1. verify the war file was created in `target/wildbook-X.Y.Z.war` (where X.Y.Z is the current version number).
+1. cd to the deploy directory `cd ~/wildbook-dev/webapps/wildbook` 
+1. deploy your warfile `jar -xvf /code/directory/Wildbook/target/wildbook-X.Y.Z.war`
+
+### Deploy
+1. `cd` to the `devops/development` directory in the code repo
+1. run `docker-compose up [-d]`
+1. To verify successful launch, open in browser `http://localhost:81/` when tomcat has started. Default login of username/password `tomcat`/`tomcat123` should work.
+
+Note: if you're running docker as root, you may want to explicitly set your deploy directory path to include your user, i.e., `WILDBOOK_BASE_DIR=~USER/wildbook-dev`
+
+### Redeploy and rebuild
+For any local testing, you will need to rebuild and redeploy your changes.
+
+#### War file
+
+If you make code changes and want to test them locally, you can create and deploy a new war file using the [Build war file](#build-war-file) and [Deploy](#deploy) instructions. Then use `docker-compose restart wildbook` to test your changes.
+
+#### React-only changes
+
+If you are working on react-only work, you can test your changes without updating the full war file.
+Use npm to build and deploy to your local deployment
+
+If you have your dev environment set up correctly, this will build the React app and copy it into your local deployment directory for you.
+
+1. `cd` to `REPO/frontend/`
+1. run `npm run deploy-dev`
+1. refresh your browser page by visiting either http://localhost:81/react/ for local testing or https://public.url.example.com/react/ for the public-facing deployment
+
+#### Manually rebuild react-only changes
+
+1. `cd` to `REPO/frontend/`
+1. run `npm run build`
+1. copy everything under `frontend/build/` to the deployed `wildbook/react/` directory you created during setup
+1. refresh your browser page by visiting either http://localhost:81/react/ for local testing or https://public.url.example.com/react/ for the public-facing deployment

_sources/contribute/index.md

@@ -0,0 +1,34 @@
+# Ways to Contribute
+
+```{toctree}
+:hidden:
+
+dev-setup
+pr-workflow
+code-guide
+copy-guide
+roadmap
+```
+
+```{note}
+We currently only support development setup on Linux (Ubuntu), but will do our best to support Windows and Mac developers.
+```
+
+Wildbook is open source software intended to combat extinction. While historically considered open repo software, where anyone was free to download and modify the tools, the team has adopted new methods as climate change accelerates. We are working to build a thriving open source community of users, researchers, and developers alike who rely on each other to advance the mission of protecting the planet. 
+
+If you want to help, there's any number of ways that contribute directly to the mission.
+
+* Provide data: If you have relevant species data that you want to provide to researchers, check out the available Wildbooks and see if there's a match. We're also putting together a list of high-interest data deficient species
+* Develop code: unit tests, tech debt, new features, bug fixes. All of our products are available for direct contribution. See the Pull request workflow for more information.
+* Donate: As a non-profit, we are working to provide maximum value at minimum cost. However, we must still cover the costs of things such as storage and processing for our various platforms. 
+
+## Add to documentation
+All Wild Me documentation, be it community, user, or developer docs, is hosted on GitHub. As such, you can contribute to the docunentation through the standard PR flow.
+
+_Guidelines coming soon_
+
+## Coming soon
+* Test and issue reporting
+* API documentation
+* System and documentation translations
+* ML training and development