Skip to content

Commit 9f9d934

Browse files
coding-ai-assistant[bot]florath
coding-ai-assistant[bot]
and
florath
authored
Streamline documentation and remove redundancy [AI-assisted] (#1016)
* docs: streamline documentation and remove redundancy [AI-assisted] Major documentation improvements to eliminate repetition and improve organization: **README.md:** - Add system requirements section mentioning external dependencies - Reference quick-start guide for detailed installation instructions **docs/quick-start.md:** - Complete rewrite from 87 to 400+ lines with comprehensive coverage - Add platform-specific installation instructions (Windows, macOS, Linux) - Add Git installation requirements for all platforms - Add troubleshooting for retraction_watch Git dependency issues - Cover all commands from README TL;DR section - Add first-time setup, sync, and status commands - Add performance tips and example outputs **docs/troubleshooting.md:** - Streamline from 545 to 190 lines by removing theoretical edge cases - Add Git-related troubleshooting for issue #1015 (actual user report) - Add log file troubleshooting (.aletheia-probe/aletheia-probe.log) - Focus on real user issues vs theoretical problems - Remove complex performance tuning and configuration edge cases - Reference quick-start guide for Git installation **docs/user-guide.md:** - Reduce from 1059 to 890 lines by removing redundant content - Replace installation section with reference to quick-start guide - Replace troubleshooting section with reference to troubleshooting guide - Focus on advanced usage rather than duplicating basic setup **Key Benefits:** - Each document has clear, non-overlapping purpose - Eliminates user confusion from repetitive content - Addresses real Windows Git dependency issue from user reports - Better user experience with focused, comprehensive guides References #1015 * fix: correct log file location to current directory [AI-assisted] The .aletheia-probe directory and log files are created in the current working directory where aletheia-probe is executed, not in the home directory. Fixed file paths: - .aletheia-probe/aletheia-probe.log (not ~/.aletheia-probe/) - Updated commands for viewing logs in troubleshooting guide - Clarified location in bug reporting instructions --------- Co-authored-by: florath-ai-assistant[bot] <Andreas.Florath@telekom.de>
1 parent 93adcc8 commit 9f9d934

File tree

4 files changed

+322
-641
lines changed

4 files changed

+322
-641
lines changed

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,14 @@ Aletheia-Probe is a command-line tool for evaluating the legitimacy of academic
1313

1414
**About the Name**: The name "Aletheia" (ἀλήθεια) comes from ancient Greek philosophy, where it represents the concept of truth and unconcealment. In Greek mythology, Aletheia was personified as the goddess or spirit (daimona) of truth and sincerity. This reflects the tool's core mission: to reveal the truth about academic journals and conferences, helping researchers distinguish legitimate venues from predatory ones.
1515

16+
## System Requirements
17+
18+
Aletheia-Probe requires external system dependencies beyond Python. Before installation, ensure your system has the required programs installed. Platform-specific installation instructions are available in the [Quick Start Guide](docs/quick-start.md#system-requirements).
19+
20+
**Required System Dependencies:**
21+
- **Git** - Required for retraction data synchronization
22+
- **Python 3.10+** - Runtime environment
23+
1624
## TL;DR
1725

1826
Aletheia-Probe helps answer two critical questions for researchers:

‎docs/quick-start.md‎

Lines changed: 182 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,195 @@
1-
# Quick Start
1+
# Quick Start Guide
22

3-
## Installation
3+
This guide provides complete installation and setup instructions for Aletheia-Probe across all supported platforms.
4+
5+
## System Requirements
6+
7+
Before installing Aletheia-Probe, ensure your system has the required dependencies:
8+
9+
### Core Requirements
10+
- **Python 3.10 or higher** - Runtime environment
11+
- **Git** - Required for retraction data synchronization
12+
13+
### Platform-Specific Installation Instructions
14+
15+
#### Windows
16+
17+
**1. Install Python:**
18+
- Download from [python.org](https://www.python.org/downloads/)
19+
- During installation, check "Add Python to PATH"
20+
- Verify: `python --version` in Command Prompt/PowerShell
21+
22+
**2. Install Git for Windows:**
23+
- Download from [git-scm.com](https://git-scm.com/downloads/win)
24+
- During installation, select "Git from the command line and also from 3rd-party software"
25+
- Verify: `git --version` in Command Prompt/PowerShell
26+
27+
**3. Common Windows Issues:**
28+
- If git is not recognized, restart your terminal
29+
- Check PATH: `echo %PATH%` (CMD) or `echo $env:PATH` (PowerShell)
30+
- Corporate networks may require proxy configuration
31+
32+
#### macOS
433

5-
### Prerequisites
34+
**1. Install Python (if not already present):**
35+
```bash
36+
# Using Homebrew (recommended)
37+
brew install python@3.10
38+
39+
# Or download from python.org
40+
```
41+
42+
**2. Install Git (usually pre-installed):**
43+
```bash
44+
# Check if git is available
45+
git --version
646

7-
Python 3.10 or higher is required.
47+
# If not installed, install via Homebrew
48+
brew install git
849

9-
### Install Aletheia-Probe
50+
# Or install Xcode Command Line Tools
51+
xcode-select --install
52+
```
53+
54+
#### Linux (Ubuntu/Debian)
55+
56+
**1. Install Python:**
57+
```bash
58+
# Ubuntu/Debian
59+
sudo apt update
60+
sudo apt install python3.10 python3.10-pip python3.10-venv
61+
62+
# Verify installation
63+
python3 --version
64+
```
65+
66+
**2. Install Git:**
67+
```bash
68+
# Ubuntu/Debian
69+
sudo apt install git
70+
71+
# Fedora/RHEL
72+
sudo dnf install git
73+
74+
# Arch Linux
75+
sudo pacman -S git
76+
77+
# Verify installation
78+
git --version
79+
```
80+
81+
#### Linux (Other Distributions)
82+
83+
**Python Installation:**
84+
- **Fedora/CentOS/RHEL:** `sudo dnf install python3.10 python3-pip`
85+
- **Arch Linux:** `sudo pacman -S python python-pip`
86+
- **openSUSE:** `sudo zypper install python310 python3-pip`
87+
88+
**Git Installation:**
89+
- **Fedora/CentOS/RHEL:** `sudo dnf install git`
90+
- **Arch Linux:** `sudo pacman -S git`
91+
- **openSUSE:** `sudo zypper install git`
92+
93+
## Installation
94+
95+
### Option 1: Install from PyPI (Recommended)
1096

1197
```bash
1298
pip install aletheia-probe
1399
```
14100

101+
### Option 2: Install from Source (For Development)
102+
103+
```bash
104+
git clone https://github.com/sustainet-guardian/aletheia-probe.git
105+
cd aletheia-probe
106+
pip install -e .
107+
```
108+
109+
### Verify Installation
110+
111+
```bash
112+
# Check if aletheia-probe is installed
113+
aletheia-probe --help
114+
115+
# Verify system dependencies
116+
aletheia-probe status
117+
```
118+
119+
## First-Time Setup
120+
121+
### 1. Initialize Data Sources
122+
123+
Before using Aletheia-Probe, you must sync the assessment databases:
124+
125+
```bash
126+
# Download and process data from all sources (5-10 minutes)
127+
aletheia-probe sync
128+
```
129+
130+
**What this does:**
131+
- Downloads journal lists from DOAJ, Beall's List, and other sources
132+
- Clones retraction data from GitLab repository (requires Git)
133+
- Processes and caches data for fast lookups
134+
- Creates local SQLite database (~100MB)
135+
136+
### 2. Check Installation Status
137+
138+
```bash
139+
# Verify all backends are working
140+
aletheia-probe status
141+
```
142+
143+
**Expected output:**
144+
```
145+
Aletheia-Probe Status
146+
=====================
147+
Configuration: Active
148+
Database: Connected (12 backends enabled)
149+
Cache: 125,431 journals cached
150+
Last sync: 2024-10-15 14:30:22
151+
152+
Backend Status:
153+
✅ doaj: 22,184 journals
154+
✅ bealls: 2,891 publishers
155+
✅ retraction_watch: 8,539 journals
156+
✅ algerian_ministry: 3,312 journals
157+
...
158+
```
159+
15160
## Basic Usage
16161

162+
### 1. Assess a Single Journal
163+
17164
```bash
18-
# Assess a single journal by name
19-
aletheia-probe journal "Journal of Advanced Research"
165+
# Basic journal assessment
166+
aletheia-probe journal "Nature"
20167

21168
# Include ISSN for more accurate matching
22169
aletheia-probe journal "Nature (ISSN: 0028-0836)"
23170

171+
# Get detailed JSON output
172+
aletheia-probe journal --format json --verbose "PLOS ONE"
173+
```
174+
175+
### 2. Assess BibTeX References
176+
177+
```bash
24178
# Assess all journals in a BibTeX file
25179
aletheia-probe bibtex references.bib
26180

27-
# Get detailed JSON output
28-
aletheia-probe journal --format json --verbose "PLOS ONE"
181+
# JSON output for integration with other tools
182+
aletheia-probe bibtex references.bib --format json
183+
```
184+
185+
### 3. Check Cache Status
186+
187+
```bash
188+
# Display current cache state and backend information
189+
aletheia-probe status
190+
191+
# Force refresh of all data sources
192+
aletheia-probe sync --force
29193
```
30194

31195
## BibTeX File Assessment
@@ -40,27 +204,11 @@ aletheia-probe bibtex my_references.bib
40204
aletheia-probe bibtex my_references.bib --format json
41205
```
42206

43-
**Exit Codes**:
207+
**Exit Codes:**
44208
- **0**: No predatory journals found (safe to proceed)
45209
- **1**: Predatory journals detected (action needed)
46210

47-
**Example BibTeX Output**:
48-
```
49-
BibTeX Assessment Summary
50-
========================================
51-
File: references.bib
52-
Total entries processed: 25
53-
Processing time: 12.3s
54-
55-
Assessment Results:
56-
Predatory journals: 2
57-
Legitimate journals: 18
58-
Insufficient data: 5
59-
60-
⚠️ WARNING: Predatory journals detected!
61-
```
62-
63-
**Integration with CI/CD**:
211+
**Integration with CI/CD:**
64212
```bash
65213
# In your build script
66214
if aletheia-probe bibtex references.bib; then
@@ -71,16 +219,11 @@ else
71219
fi
72220
```
73221

74-
## Single Journal Example Output
222+
## Next Steps
75223

76-
```json
77-
{
78-
"assessment": "legitimate",
79-
"confidence": 0.92,
80-
"sources": ["DOAJ", "Retraction Watch"],
81-
"reasoning": [
82-
"Found in DOAJ with verified publisher information",
83-
"Low retraction rate (0.1% over 5 years)"
84-
]
85-
}
86-
```
224+
- **Advanced Usage:** See the [User Guide](user-guide.md) for detailed features
225+
- **Research Applications:** Check [Research Applications Guide](research-applications.md) for systematic literature reviews
226+
- **API Reference:** Explore [API Documentation](api-reference/) for custom integrations
227+
- **Configuration:** Review [Configuration Reference](configuration.md) for advanced settings
228+
229+
**Need help?** Check the [Troubleshooting Guide](troubleshooting.md) or [open an issue](https://github.com/sustainet-guardian/aletheia-probe/issues).

0 commit comments

Comments
 (0)