feat: rewrite Academic CLI for Python 3.11 (#121)

Changes

- rewrite Academic CLI for Python v3.11
- based on user feedback, remove dependency on Hugo to be installed on user's PC
  - hence, the tool is now framework-agnostic again, so can be used with any website generator or even for writing  Markdown-formatted books
- remove deprecated features such as JS/CSS asset concatenation for offline sites
- migrate from pipenv to Poetry for dependency management (latest best practice)

Author: gcushen

MANIFEST.in

@@ -1,14 +1,14 @@
 .PHONY: black lint test publish
 
 format:
-	isort --profile black .
-	black .
+	poetry run isort --profile black .
+	poetry run black .
 
 lint:
-	flake8
+	poetry run flake8
 
 test:
-	python -m pytest
+	poetry run pytest
 
 publish:
-	python setup.py publish
+	poetry publish --build --dry-run

Makefile

@@ -34,9 +34,9 @@ Support development of the Academic CLI:
 
 ## Prerequisites
 
-1. Install [Python 3.6+](https://realpython.com/installing-python/) if it’s not already installed
+1. Install [Python 3.11+](https://realpython.com/installing-python/) if it’s not already installed
 
-### Additional prerequisites only if you are creating a website with Hugo
+### For Building a Website with Hugo (Optional)
 
 1. Create a [Hugo](https://gohugo.io) website such as by using the [Hugo Academic Starter](https://github.com/wowchemy/starter-hugo-academic) template for the [Wowchemy](https://wowchemy.com) website builder
 1. [Download your site from GitHub, installing Hugo and its dependencies](https://wowchemy.com/docs/getting-started/install-hugo-extended/)
@@ -49,24 +49,18 @@ Support development of the Academic CLI:
 Open your Terminal or Command Prompt app and install the Academic CLI tool:
 
     pip3 install -U academic
-
-Alternatively, install Academic CLI v0.5.1 if you do not wish to install Hugo on your computer:
-
-    pip3 install academic==0.5.1
 
-Or, help test the lastest development version:
+Or, help test the latest development version:
 
     pip3 install -U git+https://github.com/wowchemy/hugo-academic-cli.git
 
 ## Usage
 
-Use the `cd` command to navigate to your website folder in the terminal:
-
-    cd <MY_WEBSITE_FOLDER>
+Download references from your reference manager, such as Zotero, in the Bibtex format.
 
-**Help:**
+Use the `cd` command to navigate to the folder containing your Bibtex file:
 
-    academic
+    cd <MY_BIBTEX_FOLDER>
 
 **Import publications:**
 
@@ -91,10 +85,6 @@ Optional arguments:
 
 After importing publications, [a full text PDF and image can be associated with each item and further details added via extra parameters](https://wowchemy.com/docs/content/publications/).
 
-**Run a Hugo command (pass-through):**
-
-    academic server
-
 ## Contribute
 
 Interested in contributing to **open source** and **open science**?
@@ -105,10 +95,10 @@ Check out the [open issues](https://github.com/wowchemy/hugo-academic-cli/issues
 
 For local development, clone this repository and use Pipenv to install the tool using the following commands:
 
-    git clone https://github.com/wowchemy/hugo-academic-cli.git
-    cd hugo-academic-cli
-    pip3 install pipenv
-    pipenv install -e .
+    git clone https://github.com/wowchemy/bibtex-to-markdown.git
+    cd bibtex-to-markdown
+    poetry install
+    poetry run academic import --bibtex=tests/data/article.bib --publication-dir=debug --overwrite
 
 Preparing a contribution:
 

Pipfile

@@ -3,18 +3,17 @@
 import argparse
 import logging
 import os
-import subprocess
 import sys
 from argparse import RawTextHelpFormatter
 
-from academic import __version__ as version
-from academic import utils
-from academic.import_assets import import_assets
 from academic.import_bibtex import import_bibtex
+from academic.version import VERSION
 
 # Initialise logger.
 logging.basicConfig(
-    format="%(asctime)s %(levelname)s: %(message)s", level=logging.WARNING, datefmt="%I:%M:%S%p",
+    format="%(asctime)s %(levelname)s: %(message)s",
+    level=logging.WARNING,
+    datefmt="%I:%M:%S%p",
 )
 log = logging.getLogger(__name__)
 
@@ -32,14 +31,17 @@ def parse_args(args):
 
     # Initialise command parser.
     parser = argparse.ArgumentParser(
-        description=f"Hugo Academic CLI v{version}\nhttps://github.com/wowchemy/hugo-academic-cli", formatter_class=RawTextHelpFormatter,
+        description=f"Hugo Academic CLI v{VERSION}\nhttps://github.com/wowchemy/bibtex-to-markdown",
+        formatter_class=RawTextHelpFormatter,
     )
     subparsers = parser.add_subparsers(help="Sub-commands", dest="command")
 
     # Sub-parser for import command.
     parser_a = subparsers.add_parser("import", help="Import data into Academic")
     parser_a.add_argument(
-        "--assets", action="store_true", help="Import third-party JS and CSS for generating an offline site",
+        "--assets",
+        action="store_true",
+        help="Import third-party JS and CSS for generating an offline site",
     )
     parser_a.add_argument("--bibtex", required=False, type=str, help="File path to your BibTeX file")
     parser_a.add_argument(
@@ -52,11 +54,17 @@ def parse_args(args):
     parser_a.add_argument("--featured", action="store_true", help="Flag publications as featured")
     parser_a.add_argument("--overwrite", action="store_true", help="Overwrite existing publications")
     parser_a.add_argument(
-        "--normalize", action="store_true", help="Normalize each keyword to lowercase with uppercase first letter",
+        "--normalize",
+        action="store_true",
+        help="Normalize each keyword to lowercase with uppercase first letter",
     )
     parser_a.add_argument("-v", "--verbose", action="store_true", required=False, help="Verbose mode")
     parser_a.add_argument(
-        "-dr", "--dry-run", action="store_true", required=False, help="Perform a dry run (Bibtex only)",
+        "-dr",
+        "--dry-run",
+        action="store_true",
+        required=False,
+        help="Perform a dry run (Bibtex only)",
     )
 
     known_args, unknown = parser.parse_known_args(args)
@@ -65,21 +73,11 @@ def parse_args(args):
     if len(args) == 0:
         parser.print_help()
         parser.exit()
-
-    # If no known arguments, wrap Hugo command.
-    elif known_args is None and unknown:
-        cmd = utils.hugo_in_docker_or_local()
-        if args:
-            cmd = " ".join([cmd, args])
-        subprocess.call(cmd)
     else:
         # The command has been recognised, proceed to parse it.
         if known_args.command and known_args.verbose:
             # Set logging level to debug if verbose mode activated.
             logging.getLogger().setLevel(logging.DEBUG)
-        if known_args.command and known_args.assets:
-            # Run command to import assets.
-            import_assets()
         elif known_args.command and known_args.bibtex:
             # Run command to import bibtex.
             import_bibtex(

Pipfile.lock

@@ -1,8 +1,6 @@
 import calendar
 import os
 import re
-import subprocess
-import time
 from datetime import datetime
 from pathlib import Path
 
@@ -12,13 +10,17 @@
 from bibtexparser.bwriter import BibTexWriter
 from bibtexparser.customization import convert_to_unicode
 
-from academic import utils
-from academic.editFM import EditableFM
+from academic.generate_markdown import EditableFM
 from academic.publication_type import PUB_TYPES, PublicationType
 
 
 def import_bibtex(
-    bibtex, pub_dir=os.path.join("content", "publication"), featured=False, overwrite=False, normalize=False, dry_run=False,
+    bibtex,
+    pub_dir=os.path.join("content", "publication"),
+    featured=False,
+    overwrite=False,
+    normalize=False,
+    dry_run=False,
 ):
     """Import publications from BibTeX file"""
     from academic.cli import AcademicError, log
@@ -37,12 +39,22 @@ def import_bibtex(
         bib_database = bibtexparser.load(bibtex_file, parser=parser)
         for entry in bib_database.entries:
             parse_bibtex_entry(
-                entry, pub_dir=pub_dir, featured=featured, overwrite=overwrite, normalize=normalize, dry_run=dry_run,
+                entry,
+                pub_dir=pub_dir,
+                featured=featured,
+                overwrite=overwrite,
+                normalize=normalize,
+                dry_run=dry_run,
             )
 
 
 def parse_bibtex_entry(
-    entry, pub_dir=os.path.join("content", "publication"), featured=False, overwrite=False, normalize=False, dry_run=False,
+    entry,
+    pub_dir=os.path.join("content", "publication"),
+    featured=False,
+    overwrite=False,
+    normalize=False,
+    dry_run=False,
 ):
     """Parse a bibtex entry and generate corresponding publication bundle"""
     from academic.cli import log
@@ -75,11 +87,17 @@ def parse_bibtex_entry(
             f.write(writer.write(db))
 
     # Prepare YAML front matter for Markdown file.
-    hugo = utils.hugo_in_docker_or_local()
     if not dry_run:
-        subprocess.call(f"{hugo} new {markdown_path}", shell=True)
-        if "docker-compose" in hugo:
-            time.sleep(2)
+        from importlib import resources as impresources
+
+        from academic import templates
+
+        inp_file = impresources.files(templates) / "publication.md"
+        with inp_file.open("rt") as f:
+            template = f.read()
+
+        with open(markdown_path, "w") as f:
+            f.write(template)
 
     page = EditableFM(Path(bundle_path), dry_run=dry_run)
     page.load(Path("index.md"))