refactor config handler and morev0.6.0

Refactored the configuration handling to use configparser; also the argument parser; generally added more 'logging';  updated template resources; and more minor things

1 files changed, 107 insertions, 62 deletions

diff --git a/README.md b/README.md
index 9e4275b..1a0a3b4 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,8 @@
 
 Inspired (initially) by Roman Zolotarev's [`ssg5`](https://rgz.ee/bin/ssg5) and [`rssg`](https://rgz.ee/bin/rssg), Luke Smith's [`lb` and `sup`](https://github.com/LukeSmithxyz/lb) and, pedantic.software's great (but *"mamador"*, as I would say in spanish) [`blogit`](https://pedantic.software/git/blogit/).
 
-I'm writing this in *pYtHoN* (thought about doing it in Go, but I'm most comfortable with Python at the moment) because I want features from all of these minimal programs (and more), but I don't really want to be stitching each one of the features on any of these programs, because they're written in a way to only work as how they were first imagined to work like; I already tried adding features to `ssg` and ended up rewriting it in POSIX shell, but it was a pain in the ass when I tried to add even more, and don't get me started on trying to extend `blogit`... And also because I want to.
-
 ## Current features
 
-**This is still a WIP. Still doesn't build `sitemap.xml` or `rss.xml` files.**
-
 - [x] Build static site parsing `markdown` files ( `*.md` -> `*.html`)
 	- [x] ~~Using plain `*.html` files for templates.~~ Changed to Jinja templates.
 		- [x] Would like to change to something more flexible and easier to manage ([`jinja`](https://jinja.palletsprojects.com/en/3.0.x/), for example).
@@ -15,15 +11,20 @@ I'm writing this in *pYtHoN* (thought about doing it in Go, but I'm most comfort
 	- [x] Tag functionality.
 	- [ ] Open Graph (and similar) support. (Technically, this works if you add the correct metadata to the `*.md` files and use the variables available for Jinja)
 - [x] Build `sitemap.xml` file.
+	- [ ] Include manually added `*.html` files.
 - [x] Build `rss.xml` file.
 	- [ ] Join the `static_url` to all relative URLs found to comply with the [RSS 2.0 spec](https://validator.w3.org/feed/docs/rss2.html) (this would be added to the parsed HTML text extracted from the MD files, so it would be available to the created `*.html` and `*.xml` files). Note that depending on the reader, it will append the URL specified in the RSS file or use the [`xml:base`](https://www.rssboard.org/news/151/relative-links) specified ([newsboat](https://newsboat.org/) parses `xml:base`).
+	- [ ] Include manually added `*.html` files.
 - [x] Only build page if `*.md` is new or updated.
 	- [ ] Extend this to tag pages and index (right now all tags and index is built no matter if no new/updated file is present).
-- [x] Configuration file as an alternative to using command line flags (configuration file options are prioritized).
+- [x] Configuration file. ~~as an alternative to using command line flags (configuration file options are prioritized).~~ 
+	- [x] Use [`configparser`](https://docs.python.org/3/library/configparser.html) instead of custom config handler.
+
+**Please note that I've removed the use of command line flags for now as it was too much bloat and unnecessary.**
 
 ### To be added/fixed
 
-- [ ] Avoid the program to freak out when there are directories created in advance.
+- [x] Avoid the program to freak out when there are directories created in advance.
 - [ ] Provide more meaningful error messages when you are missing mandatory tags in your `.md` files.
 
 ### Markdown features
@@ -48,31 +49,35 @@ Just install it with `pip`:
 pip install pyssg
 ```
 
-*EW!*, I know..., I will try to make a PKBUILD and release it in AUR or something; hit me up if you do it to add it here.
+Will add a PKBUILD (and possibly submit it to the AUR) sometime later.
 
 ## Usage
 
-It is intended to be used as a standalone terminal program running on the "root" directory where you have the `src` and `dst` directories in (defaults for both flags).
-
-First initialize the directories you're going to use for the source files and destination files:
+1. Get the default configuration file:
 
 ```sh
-pyssg -s src_dir -d dst_dir -i
+pyssg --copy-default-config -c <path/to/config>
 ```
-You do not have to create any directories, in advance, the command above will do it.
-Actually for the moment I will encourage you to **not create** any directories in advance.
 
-That creates the desired directories with the basic templates that can be edited as desired (see variables available for Jinja below). Place your `*.md` files somewhere inside the source directory (`src_dir` in the command above), but outside of the `templates` directory. It accepts sub-directories.
+Where `-c` is optional as by default `$XDG_CONFIG_HOME/pyssg/config.ini` is used.
+
+2. Edit the config file created as needed.
 
-Strongly recommended to edit the `rss.xml` template.
+- `config.ini` is parsed using Python's [`configparser`](https://docs.python.org/3/library/configparser.html), [more about the config file](#config-file).
 
-Build the site with:
+3. Initialize the directory structures (source, destination, template) and move template files:
 
 ```sh
-pyssg -s src_dir -d dst_dir -t plt_dir -u https://base.url -b
+pyssg -i
 ```
 
-Remember to add the mandatory meta-data keys to your `.md` files, these are:
+- You can modify the basic templates as needed (see [variables available for Jinja](#available-jinja-variables)).
+
+- Strongly recommended to edit the `rss.xml` template.
+
+4. Place your `*.md` files somewhere inside the source directory. It accepts sub-directories.
+
+- Remember to add the mandatory meta-data keys to your `.md` files, these are:
 
 ```
 title: the title of your blog entry or whatever
@@ -81,54 +86,94 @@ lang: the language the entry is written on
 summary: a summary of the entry
 ```
 
-You can add more meta-data keys as long as it is [Python-Markdown compliant](https://python-markdown.github.io/extensions/meta_data/).
+- You can add more meta-data keys as long as it is [Python-Markdown compliant](https://python-markdown.github.io/extensions/meta_data/), and these will ve [available as Jinja variables](#available-jinja-variables).
+
+- Also strongly recomended to add the `tags` metadata so that `pyssg` generates some nice filtering tags.
 
-Also strongly recomended to add the `tags` test for `pyssg` to generate some nice filtering tags.
+5. Build the `*.html` with:
+
+```sh
+pyssg -b
+```
+
+- After this, you have ready to deploy `*.html` files.
+
+- For now, the building option also creates the `rss.xml` and `sitemap.xml` files based on templates, including only all converted `*.md` files (and processed tags in case of the sitemap), meaning that separate `*.html` files should be included manually in the template.
+
+## Config file
+
+All sections/options need to be compliant with the [`configparser`](https://docs.python.org/3/library/configparser.html).
+
+At least the sections and options given in the default config should be present:
+
+```ini
+[path]
+src=src # source
+dst=dst # destination
+plt=plt # template
+[url]
+main=https://example.com
+static=https://static.example.com # used for static resources (images, js, css, etc)
+default_image=/images/default.png # this will be appended to 'static' at the end
+[fmt] # % needs to be escaped with another %
+date=%%a, %%b %%d, %%Y @ %%H:%%M %%Z
+list_date=%%b %%d
+list_sep_date=%%B %%Y
+[info]
+title=Example site
+[other]
+force=False
+```
+
+Along with these, these extra ones will be added on runtime:
+
+```ini
+[fmt]
+rss_date=%%a, %%d %%b %%Y %%H:%%M:%%S GMT # fixed
+sitemap_date=%%Y-%%m-%%d # fixed
+[info]
+version= # current 'pyssg' version (0.5.1.dev16, for example)
+rss_run_date= # date the program was run, formatted with 'rss_date'
+sitemap_run_date= # date the program was run, formatted with 'sitemap_date'
+```
 
-So...that creates all `*.html` for the site and can be easily moved to the server. Here, the `-u` flag is technically optional in the sense that you'll not receive a warning/error, but it's used to prepend links with this URL (not strictly required everywhere), so don't ignore it; also don't include the trailing `/`.
+You can add any other option/section that you can later use in the Jinja templates via the exposed config object. 
 
-For now, the `-b`uild tag also creates the `rss.xml` and `sitemap.xml` files based on templates including only all converted `*.md` files (and processed tags in case of the sitemap), meaning that separate `*.html` files should be included manually in the template.
+Other requisites are:
 
-For more options/flags just checkout `pyssg -h`.
+- Urls shouldn't have the trailing slash `/`.
+- The only character that needs to be escaped is `%` with another `%`.
 
 ## Available Jinja variables
 
-Here is the list of variables that you can use specific Jinja templates with a short description. Note that all urls are without the trailing slash `/`.
-
-- `config` (`Configuration`) (all): configuration object containing general/global attributes, the useful ones being:
-	- `title` (`str`): title of the website.
-	- `url` (`str`): base url of the website.
-	- `static_url` (`str`): base static url where all static files are located, mostly needed for correct rss feed generator when using a `base` tag and using relative links to files. For more, see [<base>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base).
-	- `default_image_url` (`str`): as defined in `DEFAULT_IMAGE_URL` configuration option.
-	- `version` (`str`): version in numeric form, i.e. `0.5.0`.
-	- `run_date` (`str`): date when the program was run, with format required for rss.
-- Pages:
-	- `all_pages` (`list(Page)`) (all): list of all the pages, sorted by creation time, reversed.
-	- `page` (`Page`) (`page.html`): page object that contains the following attributes:
-		- `title` (`str`): title of the page.
-		- `author` (`str`): author of the page.
-		- `content` (`str`): actual content of the page.
-		- `cdatetime` (`str`): creation datetime object of the page.
-		- `cdate` (`str`): formatted `cdatetime` as the configuration option `DATE_FORMAT`.
-		- `cdate_list` (`str`): formatted `cdatetime` as the configuration option `LIST_DATE_FORMAT`.
-		- `cdate_list_sep` (`str`): formatted `cdatetime` as the configuration option `LIST_SEP_DATE_FORMAT`.
-		- `cdate_rss` (`str`): formatted `cdatetime` as required by rss.
-		- `cdate_sitemap` (`str`): formatted `cdatetime` as required by sitemap.
-		- `mdatetime` (`str`): modification datetime object of the page. Defaults to None.
-		- `mdate` (`str`): formatted `mdatetime` as the configuration option `DATE_FORMAT`. Defaults to None.
-		- `mdate_list` (`str`): formatted `mdatetime` as the configuration option `LIST_DATE_FORMAT`.
-		- `mdate_list_sep` (`str`): formatted `mdatetime` as the configuration option `LIST_SEP_DATE_FORMAT`.
-		- `mdate_rss` (`str`): formatted `mdatetime` as required by rss.
-		- `mdate_sitemap` (`str`): formatted `mdatetime` as required by sitemap.
-		- `summary` (`str`): summary of the page, as specified in the `*.md` file.
-		- `lang` (`str`): page language, used for the general `html` tag `lang` attribute.
-		- `tags` (`list(tuple(str))`): list of tuple of tags of the page, containing the name and the url of the tag, in that order. Defaults to empty list.
-		- `url` (`str`): url of the page, this already includes the `config.url`.
-		- `image_url` (`str`): image url of the page, this already includes the `config.static_url`. Defaults to the `DEFAULT_IMAGE_URL` configuration option.
-		- `next/previous` (`Page`): reference to the next or previous page object (containing all these attributes). Defaults to None
-		- `og` (`dict(str, str)`): dict for object graph metadata.
-		- `meta` (`dict(str, list(str))`): meta dict as obtained from python-markdown, in case you use a meta tag not yet supported, it will be available there.
-- Tags:
-	- `tag` (`tuple(str)`) (`tag.html`): tuple of name and url of the current tag.
-	- `tag_pages` (`list(Page)`) (`tag.html`): similar to `all_pages` but contains all the pages for the current tag.
-	- `all_tags` (`list(tuple(str))`) (all): similar to `page.tags` but contains all the tags.
+These variables are exposed to use within the templates. The below list is in the form of *variable (type) (available from): description*. `section/option` describe config file section and option and `object.attribute` corresponding object and it's attribute.
+
+- `config` (`ConfigParser`) (all): parsed config file plus the added options internally (as described in [config file](#config-file)).
+- `all_pages` (`list(Page)`) (all): list of all the pages, sorted by creation time, reversed.
+- `page` (`Page`) (`page.html`): contains the following attributes (genarally these are parsed from the metadata in the `*.md` files):
+	- `title` (`str`): title of the page.
+	- `author` (`str`): author of the page.
+	- `content` (`str`): actual content of the page, this is the `html`.
+	- `cdatetime` (`str`): creation datetime object of the page.
+	- `cdate` (`str`): formatted `cdatetime` as the config option `fmt/date`.
+	- `cdate_list` (`str`): formatted `cdatetime` as the config option `fmt/list_date`.
+	- `cdate_list_sep` (`str`): formatted `cdatetime` as the config option `fmt/list_sep_date`.
+	- `cdate_rss` (`str`): formatted `cdatetime` as required by rss.
+	- `cdate_sitemap` (`str`): formatted `cdatetime` as required by sitemap.
+	- `mdatetime` (`str`): modification datetime object of the page. Defaults to `None`.
+	- `mdate` (`str`): formatted `mdatetime` as the config option `fmt/date`. Defaults to `None`.
+	- `mdate_list` (`str`): formatted `mdatetime` as the config option `fmt/list_date`.
+	- `mdate_list_sep` (`str`): formatted `mdatetime` as the config option `fmt/list_sep_date`.
+	- `mdate_rss` (`str`): formatted `mdatetime` as required by rss.
+	- `mdate_sitemap` (`str`): formatted `mdatetime` as required by sitemap.
+	- `summary` (`str`): summary of the page, as specified in the `*.md` file.
+	- `lang` (`str`): page language, used for the general `html` tag `lang` attribute.
+	- `tags` (`list(tuple(str))`): list of tuple of tags of the page, containing the name and the url of the tag, in that order. Defaults to empty list.
+	- `url` (`str`): url of the page, this already includes the `url/main` from config file.
+	- `image_url` (`str`): image url of the page, this already includes the `url/static`. Defaults to the `url/default_image` config option.
+	- `next/previous` (`Page`): reference to the next or previous page object (containing all these attributes). Defaults to `None`.
+	- `og` (`dict(str, str)`): dict for object graph metadata.
+	- `meta` (`dict(str, list(str))`): meta dict as obtained from python-markdown, in case you use a meta tag not yet supported, it will be available there.
+- `tag` (`tuple(str)`) (`tag.html`): tuple of name and url of the current tag.
+- `tag_pages` (`list(Page)`) (`tag.html`): similar to `all_pages` but contains all the pages for the current tag.
+- `all_tags` (`list(tuple(str))`) (all): similar to `page.tags` but contains all the tags.