0
# Setup and Utilities
1

2
Helper functions for project setup, README generation, and development workflows. These utilities are particularly useful for Python package development, enabling conversion from Creole markup to ReStructuredText for PyPI compatibility and automated documentation workflows.
3

4
## Capabilities
5

6
### README Management
7

8
Functions for converting and maintaining README files in multiple formats for package distribution.
9

10
```python { .api }
11
def get_long_description(package_root: str, filename: str = 'README.creole', 
12
                        raise_errors: bool = None) -> str: ...
13
def update_rst_readme(package_root: str, filename: str = 'README.creole') -> None: ...
14
def assert_rst_readme(package_root: str, filename: str = 'README.creole') -> None: ...
15
def update_creole_rst_readme() -> None: ...
16
```
17

18
**Usage Examples:**
19

20
```python
21
from creole.setup_utils import get_long_description, update_rst_readme, assert_rst_readme
22

23
# Convert README.creole to ReStructuredText for setup.py
24
long_desc = get_long_description('./my_package')
25
# Returns ReStructuredText version of README.creole content
26

27
# Update README.rst from README.creole
28
update_rst_readme('./my_package')
29
# Creates/updates README.rst file
30

31
# Validate README files are in sync (for testing)
32
assert_rst_readme('./my_package')
33
# Raises AssertionError if README.rst is out of date
34

35
# Update from command line (if using as entry point)
36
update_creole_rst_readme()
37
# Updates README.rst in current directory
38
```
39

40
### Legacy README Conversion (Deprecated)
41

42
Convert Creole README to ReStructuredText for setup.py long_description.
43

44
```python { .api }
45
def get_long_description(package_root: str, filename: str = 'README.creole', 
46
                        raise_errors: bool = None) -> str
47
```
48

49
**Parameters:**
50
- `package_root`: Path to package root directory
51
- `filename`: README filename (default: 'README.creole')
52
- `raise_errors`: Whether to raise errors on conversion failure (auto-detected if None)
53

54
**Returns:** ReStructuredText string suitable for PyPI
55

56
**Usage Examples:**
57

58
```python
59
# In setup.py (deprecated approach)
60
from creole.setup_utils import get_long_description
61
import warnings
62

63
# Suppress deprecation warning if needed
64
with warnings.catch_warnings():
65
    warnings.simplefilter("ignore", DeprecationWarning)
66
    long_description = get_long_description('.')
67

68
setup(
69
    name='my-package',
70
    long_description=long_description,
71
    long_description_content_type='text/x-rst',
72
    # ... other setup parameters
73
)
74
```
75

76
### README Update Utilities
77

78
Modern utilities for maintaining synchronized README files.
79

80
```python { .api }
81
def update_rst_readme(package_root: str, filename: str = 'README.creole') -> None
82
```
83

84
**Parameters:**
85
- `package_root`: Path to package root directory  
86
- `filename`: Source Creole filename (default: 'README.creole')
87

88
**Usage Examples:**
89

90
```python
91
from creole.setup_utils import update_rst_readme
92

93
# Update README.rst from README.creole
94
update_rst_readme('/path/to/my_package')
95

96
# Custom source filename
97
update_rst_readme('/path/to/my_package', 'docs/README.creole')
98

99
# Use in build scripts
100
import os
101
package_dir = os.path.dirname(__file__)
102
update_rst_readme(package_dir)
103
```
104

105
### README Validation
106

107
Validate that ReStructuredText README is up-to-date with Creole source.
108

109
```python { .api }
110
def assert_rst_readme(package_root: str, filename: str = 'README.creole') -> None
111
```
112

113
**Parameters:**
114
- `package_root`: Path to package root directory
115
- `filename`: Source Creole filename (default: 'README.creole')
116

117
**Raises:** `AssertionError` if README.rst is out of date or missing
118

119
**Usage Examples:**
120

121
```python
122
from creole.setup_utils import assert_rst_readme
123
import unittest
124

125
class TestDocumentation(unittest.TestCase):
126
    def test_readme_is_current(self):
127
        """Ensure README.rst matches README.creole"""
128
        assert_rst_readme('.')
129
        
130
# In CI/build validation
131
try:
132
    assert_rst_readme('/project/root')
133
    print("README files are synchronized")
134
except AssertionError:
135
    print("ERROR: README.rst is out of date, run update_rst_readme()")
136
    exit(1)
137
```
138

139
### Command Line Entry Point
140

141
Entry point for command-line README updates.
142

143
```python { .api }
144
def update_creole_rst_readme() -> None
145
```
146

147
**Usage Examples:**
148

149
```python
150
# Called by command line tool
151
# $ update_rst_readme
152
from creole.setup_utils import update_creole_rst_readme
153
update_creole_rst_readme()  # Updates README.rst in current directory
154
```
155

156
### Error Handling Configuration  
157

158
Utility for determining when to raise errors based on command line context.
159

160
```python { .api }
161
def should_raise_errors() -> bool: ...
162
```
163

164
**Returns:** True if errors should be raised based on sys.argv analysis
165

166
**Usage Examples:**
167

168
```python
169
from creole.setup_utils import should_raise_errors
170

171
# Automatically determine error handling
172
if should_raise_errors():
173
    # Running in build/check context, raise errors
174
    strict_mode = True
175
else:
176
    # Running in install context, be permissive
177
    strict_mode = False
178
```
179

180
## Integration Patterns
181

182
### Modern Setup.py Integration
183

184
```python
185
# setup.py
186
from pathlib import Path
187
from creole.setup_utils import update_rst_readme
188

189
# Ensure README.rst is current
190
package_root = Path(__file__).parent
191
update_rst_readme(str(package_root))
192

193
# Read the updated file
194
readme_rst = (package_root / "README.rst").read_text(encoding='utf-8')
195

196
setup(
197
    name='my-package',
198
    long_description=readme_rst,
199
    long_description_content_type='text/x-rst',
200
    # ... other parameters
201
)
202
```
203

204
### Poetry Integration
205

206
```python
207
# In a build script called by poetry
208
from creole.setup_utils import update_rst_readme
209

210
def build_docs():
211
    update_rst_readme('.')
212
    print("README.rst updated from README.creole")
213

214
if __name__ == '__main__':
215
    build_docs()
216
```
217

218
### CI/CD Validation
219

220
```python
221
# In test suite or CI script
222
import unittest
223
from creole.setup_utils import assert_rst_readme
224

225
class DocumentationTests(unittest.TestCase):
226
    def test_readme_synchronization(self):
227
        """Verify README files are synchronized"""
228
        try:
229
            assert_rst_readme('.')
230
        except AssertionError:
231
            self.fail("README.rst is out of date. Run 'update_rst_readme' to fix.")
232
```
233

234
### Makefile Integration
235

236
```python
237
# build_readme.py
238
from creole.setup_utils import update_rst_readme
239
import sys
240

241
if __name__ == '__main__':
242
    package_root = sys.argv[1] if len(sys.argv) > 1 else '.'
243
    update_rst_readme(package_root)
244
    print(f"Updated README.rst in {package_root}")
245
```
246

247
```makefile
248
# Makefile
249
update-readme:
250
    python build_readme.py
251

252
check-readme:
253
    python -c "from creole.setup_utils import assert_rst_readme; assert_rst_readme('.')"
254

255
.PHONY: update-readme check-readme
256
```
257

258
## Constants
259

260
```python { .api }
261
RAISE_ERRORS_ARGS: tuple = (
262
    'check', 'register', 'sdist', 'bdist', 'upload',
263
    '--long-description', '--restructuredtext'
264
)
265
```
266

267
Commands and arguments that indicate strict error handling should be enabled.
268

269
## Error Handling
270

271
The utilities provide different error handling modes:
272

273
- **Strict mode**: Enabled during package building, checking, and uploading
274
- **Permissive mode**: Enabled during installation to avoid blocking package installation
275
- **Validation mode**: Always raises errors for testing and CI environments
276

277
Conversion errors are handled gracefully in permissive mode by prefixing the original content with error information, ensuring package installation continues even with markup conversion issues.