LCPQ/spip2md
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

better install & config instructions

Browse Source
This commit is contained in:
Guilhem Fauré 2023-06-15 18:12:19 +02:00
parent f82a688187
commit dc80f32df5
2 changed files with 61 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
README.md
View File

@ -28,14 +28,32 @@ Markdown + YAML repository, usable with static site generators.
- Peewee, with a database connection for your database : - Peewee, with a database connection for your database :
- pymysql (MySQL/MariaDB) - pymysql (MySQL/MariaDB)
- PyYaml - PyYaml
- python-slugify (unidecode) - python-slugify (unidecode variant prefered)
## Installation
### Simple `pip` method
Install the package with `pip install spip2md` (or `python -m pip install spip2md`
if you don’t have pip installed).
Assuming your `$PATH` contains your `pip` install directory, you can now run
`spip2md` a normal command of the same name.
### Traditional method
Clone this git repo with command `git clone` and `cd` into the created directory.
Either make sure you have the dependencies installed system-wide, or create a
Python virtual-environment and install them inside.
You can then run `spip2md` as a Python module with command `python -m spip2md`.
Make sure to replace `spip2md` with a relative path to directory `spip2md` if you
didn’t `cd` into this repository’s directory.
## Usage ## Usage
First make sure you have the dependencies installed (system-wide or in a Make sure you have access to the SPIP database you want to export on a
Python virtual-environment).
Next, make sure you have access to the SPIP database you want to export on a
MySQL/MariaDB server. By default, `spip2md` expects a database named `spip` hosted on MySQL/MariaDB server. By default, `spip2md` expects a database named `spip` hosted on
`localhost`, with a user named `spip` of which password is `password`, but you can `localhost`, with a user named `spip` of which password is `password`, but you can
totally configure this as well as other settings in the YAML config file. totally configure this as well as other settings in the YAML config file.
@ -44,27 +62,44 @@ If you want to copy over attached files like images, you also need access to
the data directory of your SPIP website, usually named `IMG`, and either rename it the data directory of your SPIP website, usually named `IMG`, and either rename it
`data` in your current working directory, or set `data_dir` setting to its path. `data` in your current working directory, or set `data_dir` setting to its path.
Currently, the config file can be given as the only CLI parameter, or if no parameter Currently, the config file you want to use can be given as the only CLI parameter,
is given, the program searches a `spip2md.yml` file in the current working directory. or if no parameter is given, the program searches a `spip2md.yml` file in the current
Here’s the *configuration options* : working directory. Here’s the *default configuration options* with commentaries
explaining their meaning :
```yaml ```yaml
db: Name of the database (default is spip) db: spip # Name of the database
db_host: Host of the database (default is localhost) db_host: localhost # Host of the database
db_user: The database user (default is spip) db_user: spip # The database user
db_pass: The database password (default is password) db_pass: password # The database password
data_dir: The directory in which SPIP images & files are stored data_dir: data # The directory in which SPIP images & files are stored
export_languages: Array of languages to export (default is ["en",])
output_dir: The directory in which files will be written (default is output/) export_languages: ["en"] # Array of languages to export, two letter lang code
prepend_h1: Should spip2md prepend the title of articles as Markdown h1 (default true) # If set, directories will be created only for this language, according to this
prepend_id: Whether to prepend ID of the object to directory slug # language’s titles. Other languages will be written along with correct url: attribute
prepend_lang: Whether to prepend lang of the object to directory slug storage_language: null
export_drafts: Should we export drafts (default true) output_dir: output/ # The directory in which files will be written
remove_html: Should we clean remaining HTML blocks (default true)
unknown_char_replacement: Broken encoding that cannot be repaired is replaced with that prepend_h1: false # Add title of articles as Markdown h1, looks better on certain themes
clear_log: Clear logfile between runs instead of appending to (default false) # Prepend ID to directory slug, preventing collisions
clear_output: Clear output dir between runs instead of merging into (default false) # If false, a counter will be appended in case of name collision
logfile: Name of the logs file (default is spip2md.log) prepend_id: false
prepend_lang: false # Prepend lang of the object to directory slug (prenvents collision)
export_drafts: true # Should we export drafts
remove_html: true # Should we clean remaining HTML blocks
title_max_length: 40 # Maximum length of a single filename
unknown_char_replacement: ?? # String to replace broken encoding that cannot be repaired
# You probably don’t want to modify the settings below
clear_log: true # Clear logfile between runs instead of appending to
clear_output: true # Clear output dir between runs instead of merging into
logfile: log-spip2md.log # Name of the logs file
loglevel: WARNING # Refer to Python’s loglevels
logname: spip2md # Beginning of log lines
export_filetype: md # Filetype of exported text files
``` ```
## External links ## External links

4
spip2md/config.py
View File

@ -33,15 +33,16 @@ class Configuration:
db_host: str = "localhost" # Where is the DB db_host: str = "localhost" # Where is the DB
db_user: str = "spip" # A DB user with read access to SPIP database db_user: str = "spip" # A DB user with read access to SPIP database
db_pass: str = "password" # Password of db_user db_pass: str = "password" # Password of db_user
data_dir: str = "IMG/" # The directory in which SPIP images & documents are stored
export_languages = ("fr", "en") # Languages that will be exported export_languages = ("fr", "en") # Languages that will be exported
storage_language: Optional[str] = "fr" # Language of files and directories names storage_language: Optional[str] = "fr" # Language of files and directories names
data_dir: str = "IMG/" # The directory in which SPIP images & documents are stored
output_dir: str = "output/" # The directory to which DB will be exported output_dir: str = "output/" # The directory to which DB will be exported
prepend_h1: bool = False # Add the title of the article as a Markdown h1 prepend_h1: bool = False # Add the title of the article as a Markdown h1
prepend_id: bool = False # Add the ID of object before slug prepend_id: bool = False # Add the ID of object before slug
prepend_lang: bool = False # Add the lang of object before slug prepend_lang: bool = False # Add the lang of object before slug
export_drafts: bool = True # Should we export drafts as draft:true articles export_drafts: bool = True # Should we export drafts as draft:true articles
remove_html: bool = True # Should spip2md remove every HTML tags remove_html: bool = True # Should spip2md remove every HTML tags
title_max_length: int = 40 # Maximum length of a single title for directory names
unknown_char_replacement: str = "??" # Replaces unknown characters unknown_char_replacement: str = "??" # Replaces unknown characters
clear_log: bool = True # Clear log before every run instead of appending to clear_log: bool = True # Clear log before every run instead of appending to
clear_output: bool = True # Remove eventual output dir before running clear_output: bool = True # Remove eventual output dir before running
@ -50,7 +51,6 @@ class Configuration:
loglevel: str = "WARNING" # Minimum criticity of logs written in logfile loglevel: str = "WARNING" # Minimum criticity of logs written in logfile
logname: str = "spip2md" # Labelling of logs logname: str = "spip2md" # Labelling of logs
export_filetype: str = "md" # Extension of exported text files export_filetype: str = "md" # Extension of exported text files
title_max_length: int = 40 # Maximum length of a single title for directory names
# max_articles_export: int = 1000 # TODO reimplement # max_articles_export: int = 1000 # TODO reimplement
# max_sections_export: int = 500 # TODO reimplement # max_sections_export: int = 500 # TODO reimplement