Wikisource Reader Docs

Getting Started Locally:

Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites:

You will need to ensure your system meets the following requirements:

Running project Locally:

To run WSIndex locally, fork the WSIndex repository to your GitLab account, then follow these steps:

1. After forking the WSIndex repository to your GitLab account, open your fork on GitLab and copy its SSH clone URL.

   Replace YOUR_FORK_CLONE_URL in the command below with the SSH URL you copied.

   git clone YOUR_FORK_CLONE_URL

   cd wsindex

2. Initialize and Activate Virtual Environment

   # Initialize virtual environment
   virtualenv venv
   
   # Activate on Linux/macOS
   source venv/bin/activate
   
   # Activate on Windows
   .\venv\Scripts\activate

3. Install Dependencies

   pip install -r requirements.txt

4. Replace the database settings in wsindex/settings.py with the following for a lightweight SQLite database:

   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.sqlite3',
           'NAME': BASE_DIR / 'db.sqlite3',
       }
   }

5. Apply Database Migrations

   python manage.py migrate

6. Import Books from Wikidata

   python manage.py updatecatalog

7. Run Local Server

   python manage.py runserver

8. Navigate to the following address to view imported books.

   http://127.0.0.1:8000/books/

9. In case of a 404 or Not Found error, add 127.0.0.1:8000 to allowed hosts in wsindex/settings.py.

Getting Started Locally:

Follow these instructions to set up the development environment and run the application on an emulator or physical device.

Prerequisites:

You will need to ensure your development environment meets the following requirements:

Running project Locally:

To build and run the app locally, follow these steps:

1. Clone the Repository

   git clone https://github.com/cis-india/Wikisource-Reader.git

   cd Wikisource-Reader

2. Open in Android Studio

   Launch Android Studio, select File > Open, and navigate to the cloned project directory. Allow Gradle to sync and download necessary dependencies.

3. Run on Device or Emulator

   Connect a physical device via USB (with debugging enabled) or start a Virtual Device (AVD). Press Shift + F10 or click the green Run button in the toolbar.

   You can also pair your device via Wi-Fi instead of using USB. Once you enable developer mode on your Android phone, you will find options to pair via USB or Wi-Fi.

4. Pointing to Local API (Optional)

   If you are running WSIndex locally and want the app to connect to it, update the baseApiUrl in the api/BookApi to your local IP:

   // If you are running on an emulator
   private val baseApiUrl = "http://10.0.2.2:8000/books"
   
   // Use the IP address of your host machine (PC)
   // when running on a physical device.
   private val baseApiUrl = "http://192.168.100.2:8000/books"

Allowing HTTP Traffic for Local Development:

By default, Android prevents apps from connecting to servers via unencrypted HTTP. To connect the app to your local instance of WSIndex, follow these steps to configure network security:

1. Create the Network Security Directory

   In your project explorer, navigate to app/src/main/res. If an xml folder does not exist, right-click res, select New > Directory, and name it xml.

2. Create the Config File

   Right-click on the res/xml folder and select New > XML Resource File. Name it network_security_config.xml and replace its contents with the following:

   <?xml version="1.0" encoding="utf-8"?>
   <network-security-config>
       <domain-config cleartextTrafficPermitted="true">
           <!-- Host IP -->
           <domain includeSubdomains="true">192.168.100.2</domain>
           <domain includeSubdomains="true">10.0.2.2</domain>
           <domain includeSubdomains="true">127.0.0.1</domain>
       </domain-config>
   </network-security-config>

3. Link the Configuration in the Manifest

   Android requires you to register this file in the application manifest to apply the security exceptions.

   Open app/src/main/AndroidManifest.xml and add the android:networkSecurityConfig attribute inside the <application> tag:

   <application
       android:name=".WikisourceApplication"
       android:networkSecurityConfig="@xml/network_security_config"
       ...>
       <!-- Activities and Services -->
   </application>