Hexo - icarus theme 설치: git기반

이전 글 Hexo: icarus 테마 git기반 설치와 업그레이드 에 변경과 configurationsfile 을 더한 내용이다.

static file 기반 블로엔진인 Hexo에서 테마로 icarus 를 사용하려고 한다. 여기서는 icarus theme를 git으로 설치한다. 그리고 최신 버전으로 업그레이드 하는 과정을 살펴본다. 또한 icarus theme의 구성 파일에 대해서 좀 더 세부적으로 살펴본다.

  1. Icarus theme git 설치
  2. Configuration files
  3. Upgrade

1. Icarus theme git 설치

icarus 테마는 getting-started-with-icarus 에 설명이 되어 있다. 여기서는 git 을 클론해서 사용해 보도록 하겠다.


- git clone

icarus 릴리즈 페이지 https://github.com/ppoffice/hexo-theme-icarus/releases 를 확인해서 원하는 버전 번호를 찾는다. hexo 프로젝트 폴더에 들어가서 아래 같이 5.0.0 버전을 지정해서 클론을 수행한다.

1
2
$ cd PROJECT_FOLDER
$ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b 5.0.0 --depth 1

클론한 결과는 아래 같은 폴더 구조를 갖는다.

1
2
3
4
5
6
themes/icarus
├── include
├── languages
├── layout
├── scripts
└── source

- 설정

이제 hexo의 구성 파일 _config.yml 에 테마를 icarus 로 지정한다.

1
2
#_config.yml
theme: icarus

그리고 icarus 구성 파일 _config.icarus.yml 에 먼저 버전을 명시하고 icarus 테마 관련 설정을 진행한다.

1
version: 5.0.0


Configuration files

Icarus theme의 구성파일은, jyekyll 의 구성요소 + icarus 구성 파일로 제공한다. 구성 파일을 통해서 여러 형식의 화면 표현을 가능하게 한다. _config.yml 와 같은 위치에 있으면 된다.

아래는 구성파일의 우선순위 순서로 작성되어 있다:

  • _config.yml: 사이트 구성 파일 (jekyll 의 기본 구성파일)
  • _config.icarus.yml: Icarus theme 기본 구성파일.
  • 레이아웃 구성 파일
    • _config.post.yml : 글 내용 POST 레이아웃 화면/위젯 구성
    • _config.page.yml : 페이지의 레이아웃 화면/위젯 구성
  • Jykell 의 Post/page front-matter
  • (Deprecated) Legacy theme configuration file at themes/icarus/_config.yml
  • (Deprecated) Legacy layout configuration file at themes/icarus/_config.post.yml and themes/icarus/_config.page.yml

Layout Configuration Files

레이아웃 구성은 icarus theme 의 구성파일과 같은 구조를 갖는다. 모든 블로그 포스트의 레이아웃을 위해서 _config.post.yml 파일을 참조한다. 그리고 _config.page.yml 은 사용자 지정 페이지를 위한 레이아웃에 적용된다.

_config.icarus.yml 파일:

  • 세 개의 컬럼으로 사이트의 레이아웃을 배치한다.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    widgets:
    -
    type: recent_posts
    position: left
    -
    type: categories
    position: right
    -
    type: tags
    position: right

_config.post.yml 파일

  • POST는 위젯 위치를 left 로 두어서 위젯+본문의 두개 컬럼으로 구성된다.
1
2
3
4
5
6
7
8
9
10
widgets:
-
type: recent_posts
position: left
-
type: categories
position: left
-
type: tags
position: left

Post/Page Front-matter

어떤 페이지/포스트에서 사이트/레이아웃 구성을 오버라이드 하려면 해당 포스트(글) 혹은 페이지의 Front-matter 로 구성해 사용하면 된다.

작성한 포스트 source/_post/some-post.md 에 선언한 Front-matter 구성.

1
2
3
4
5
6
7
8
title: My first post
date: '2015-01-01 00:00:01'
article:
highlight:
theme: atom-one-dark
---
# Some Post

some-post.md 의 Front-matter 는 아래 사항을 오버라이드한다.

  • _config.post.yml, _config.icarus.yml 의 article.highlight 를 atom-one-dark 로 재구성한다.
  • 단, font-matter에서 title, date, updated, comments, layout, source, photos, and excerpt 등은 재정의 되지 않는다.

Site Configuration File

앞서 설명한 icarus 테마, 레이아웃, font matter 파일을 사이트 구성파일을 재정의 한 것이다.



3. Upgrade

다른 버전의 icarus theme 로 업그레이드를 하려면 기존 폴더를 백업해 두고 다시 git clone을 통해 다운로드하고 _config.icarus.yml 구성 파일에 버전과 내용을 변경해서 사용하면 된다.

예를 들어 앞서 5.0.0 버전을 백업하고 5.1.1 버전으로 업그레이드 한다면 아래 같이 기존 irarus 를 icarus_5.0.0 같이 백업해 두고 새 버전이 잘 적응되는지 확인후 정리하면 된다.

1
2
$ cd PROJECT_FOLDER/theme
$ mv icarus icarus_5.0.0

이어서 새 버전을 git clone 한다.

1
$ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b 5.1.1 --depth 1

hexo의 구성 파일 _config.icarus.yml 에 새 icarus 테마 버전을 명시한다.

1
version: 5.1.1

hexo 서버를 재시작해 정상적으로 동작하는지 확인한다. 그런데 필요한 npm 모듈 업그레이들 요구한다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$ hexo server
INFO Validating config
Inferno is in development mode.
INFO =======================================
██╗ ██████╗ █████╗ ██████╗ ██╗ ██╗███████╗
██║██╔════╝██╔══██╗██╔══██╗██║ ██║██╔════╝
██║██║ ███████║██████╔╝██║ ██║███████╗
██║██║ ██╔══██║██╔══██╗██║ ██║╚════██║
██║╚██████╗██║ ██║██║ ██║╚██████╔╝███████║
╚═╝ ╚═════╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝
=============================================

ERROR Package hexo-component-inferno's version (1.1.0) does not satisfy the required version (^2.0.2).
ERROR Please install the missing dependencies your Hexo site root directory:
ERROR npm install --save hexo-component-inferno@^2.0.2
ERROR or:
ERROR yarn add hexo-component-inferno@^2.0.2

요구에 따라 업그레이드 해주면 된다.

1
$ npm install --save hexo-component-inferno@^2.0.2

정상적으로 업그레이드 되어서 server가 실행되는 것을 확인할 수 있다. 단, hexo clean 이후 에러를 만날 수 있어 보인다.


업그레이드 후 db.json 에러 대응

clean 해서 새로 생성하기 위해서 clean 명령후 generate 를 2번 정도 실행하면 보통는 db.json 에러가 없어지는데 업그레이드 후 아래 같이 계속 발생한다.

1
2
3
INFO  === Registering Hexo extensions ===
FATAL Error: [hexo-include-markdown] Could not open db.json .
at ReadFileContext.callback (/Users/qkboo/work-blog/thinkbee.github.io/node_modules/hexo-include-markdown/lib/orverwriteCache.js:22:15)

블로그 solved-hexo-include-markdown 를 따라 다음 같이 처리했다.

1
2
3
4
#
$ npm install hexo-include-markdown --save
# clean & generate
$ hexo clean;echo "{}" > db.json;hexo generate

Upgrade to Icarus 5.2.1

2023/7월 Icarus 5.2.1 로 업그레이드 진행

1
git clone https://github.com/ppoffice/hexo-theme-icarus.git icarus -b 5.2.1

_config.icarus.yml 에 icarus theme 버전을 명시한다.

1
version: 5.2.1

서버를 재시작하고 확인한다. npm 모듈등… 문제가 없이 잘 진행된다.

참고

  1. User guide: configurations

Python - 파이썬 프로젝트 패키징과 배포하기

파이썬에서 작업한 소스를 공개/비공개 배포하기 위해서 패키징을 하는 방법을 요약, 정리했다.

파이썬 모듈 배포하기

이 글은 setuptools, builds 그리고 PyPI 업로드를 위한 twine 를 사용하고 있다.

[핵심 용어]

  • PyPi, Python Package Index: 파이썬 사용자를 위한 오픈소스 패키지의 공개 저장소 일명 PyPi
  • PyPa, 파이썬 패키징 위원회: 표준 패키징 도구/메타 데이터/파일 형식 표준을 GitHub 와 Bitbucket 을 통해서 여러 패키징 도구, 문서, 이슈 추적기를 관리하고 있다.
  • distutils: 1998년/파이썬 표준 라이브러리 최초의 빌드 및 배포 시스템. 대부분 직접 사용이 단계적으로 폐지되고 있다.
    • distutils는 파이썬 3.10부터 deprecated, 3.12에서 삭제될 예정.
  • setuptools : 2004 공개/ distutils 의 드롭인(drop-in) 대체품. distutils 와 큰 차이는 다른 패키지에 대한 의존성을 선언할 수 있다.
  • [pyproject.toml]: 2016년 setuptools의 메타 파일 setup.py 의존성을 피하고자 독립한 빌드용 선언적 메타정보 파일.
  • wheel: distutils/setuptools 에 bdist_wheel 명령을 추가하는 프로젝트이다. 파이썬 라이브러리를 바이너리 확장을 포함/크로스 플랫폼 바이너리 패키징 형식 지원 (“휠”,”휠 파일”, PEP 427 정의).

도구 설치

setuptools 기반 배포도구 설치

1
python -m pip install setuptools wheel twine

파이썬 패키징

https://packaging.python.org/en/latest/tutorials/packaging-projects/ 내용을 요약, 정리, 보충한다.

프로젝트 생성

패키징 수행하면 별도의 가상환경을 생성해서 진행한다.

프로젝트를 패키징하는 과정을 위해서 packaging_tutorial 폴더 아래에 같은 구조를 갖는다.

1
2
3
4
5
packaging_tutorial/
└── src/
└── example_package_YOUR_USERNAME_HERE/
├── __init__.py
└── example.py
  • example_package_YOUR_USERNAME_HERE : 프로젝트 이름이고 중복하지 않게 한다.
  • __init__.py : 빈 파일로 폴더를 패키지로 인식하게 한다.
  • example.py : 모듈.

example.py 모듈 소스.

1
2
def add_one(number):
return number + 1

패키징용 파일 생성

배포를 위한 프로젝트의 구성을 위해 패키징에 필요한 파일을 추가한 구조는 아래 같다.

1
2
3
4
5
6
7
8
9
packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
└── src/
│ └── example_package_YOUR_USERNAME_HERE/
│ ├── __init__.py
│ └── example.py
└── tests/
  • LICENSE : 라이센서 선언
  • pyproject.toml : 프로젝트 배포 프로젝트 생성에 사용하는 프론트엔드 빌드도구 pip, 백엔드 밸드도구 build
  • README.md
  • tests/ : 테스트 파일용 공간. Leave it empty for now.

패키징의 프론트엔드, 백엔드는 참조의 5번 항목을 살펴보자.

pyproject.toml 구성

보통 파일 내용은 아래 항목으로 구성한다. 이 파일은 TOML 형식의 구조를 따르고 있다. 여기에 대해서는 아래 참조 4번 항목 내용을 보기 바란다.

1
2
3
4
5
6
7
8
9
[build-system]
...

[project]
...

[project.urls]
...

빌드 도구를 명시하는 명세서 pyproject.toml에 setuptools 를 사용한 예이다.

1
2
3
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
  • requires : 빌드용 도구 지시.
  • build-backend : 프론트엔드 (pip)에서 빌드에 사용하는 백엔드 도구

다음은 Hatching 이란 빌드 도구를 사용한 예이다.

1
2
3
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

메타 정보를 포함한 간단한 pyproject.toml 구성 결과.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
{ name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]

[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Tracker" = "https://github.com/pypa/sampleproject/issues"

자세한 메타 정보 내역은 프로젝트 메타정보 정의를 참조한다. 주요 메타 정보의 인자:

  • [project]:
    • requires-python : 패키지가 요구하는 최소 파이썬 버전 명시
    • classifiers: pip가 인지하는 패키지에 대한 정보

README.md / LICENSE 파일

README.md 파일에 패키지 모듈를 설명한다.

1
2
3
4
5
# Example Package

This is a simple example package. You can use
[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

LICENSE 파일에 저작권을 명시한다.

1
2
3
Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy

배포 묶음 생성하기

배포를 위한 build 도구를 설치한다.

1
python3 -m pip install --upgrade build

packaging_tutorial 폴더 아래 pyproject.toml 파일이 있는 위치에서 배포를 위한 build 명령으로 소스를 패키징을 한다.

build 를 수행하면 별도의 venv 가상환경을 생성해서 의존성에 명시된 setuptools 등을 설치하고 빌드를 진행한다.

1
2
3
4
5
6
7
> python3 -m build
* Creating venv isolated environment...
* Installing packages in isolated environment... (setuptools>=61.0)
...
...
removing build\bdist.win-amd64\wheel
Successfully built example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz and example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl

이 명령의 결과로 dist 폴더에 우리 프로젝트에 대한 배포용 패키징으로 소스 패키징 .gz 파일, built distribution 패키징 .whl 2개의 파일이 생성된다.

1
2
3
dist/
├── example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
└── example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz

pip 로 wheeels 설치하기

pip 에서 built distribution 파일을 직접 설치할 수 있다. installing-from-wheels 참조.

다음은 우리 프로젝트의 wheel 패키징을 설치한다.

1
python -m pip install example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl

혹은 provides_extras 메타 정보를 사용해 추가 설치를 한다면,

1
python -m pip install './somepackage-1.0-py2.py3-none-any.whl[my-extras]'

Upload

처음 PyPi 에 업로드를 하려면 아래 2가지 단계를 거쳐서 진행해 본다.

  1. https://test.pypi.org/account/register/ 에서 등록
    1. 실제 pypi 가 아닌 튜토리얼과 테스트를 위한 곳.
  2. PyPi 업로드를 완성하려면 PyPI API token 을 발급받아야 한다.
    1. https://test.pypi.org/manage/account/#api-tokens

PyPI에 업로드가 완료되면 pip 를 통해서 패키지를 설치할 수 있다. 업로드를 위해서 Twin 패키지를 설치하고 사용해야 한다.

1
python3 -m pip install --upgrade twine

twine 모듈을 사용해서 dist/ 아래의 모든 소스/휠 패키징 묶음을 업로드할 수 있다. 지금은 testpypi 에 업로드를 해보자.

1
python3 -m twine upload --repository testpypi dist/*
  • 업로드시 username은 __token__ 사용.
  • 패스워드는 발급받은 pypi- 으로 시작하는 token 값.

업로드 진행은 아래 같을 것이다.

1
2
3
4
5
6
7
Uploading distributions to https://test.pypi.org/legacy/
Enter your username: __token__
Uploading example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.2/8.2 kB • 00:01 • ?
Uploading example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.8/6.8 kB • 00:00 • ?

여기서 repository로 testpypi 를 지정했으므로 업로드한 결과는 다음 같이 확인할 수 있다.

  • https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE

저장소에서 설치하기

위에 testpypi 에 업로드한 패키지를 설치하려면 아래 같이 --index-url 로 저장소를 지정해서 사용한다.

1
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-package-YOUR-USERNAME-HERE

PyPI 에 업로드

마지막으로 실제 패키지를 PyPI에 업로드하려면 https://pypi.org 등록을 하고, 등록한 사용자 아이디를 사용하고 --repository 인자를 제외하고 업로드하면 된다.

1
python3 -m twine upload dist/*

통합 메타 정보로서 pyproject.toml 활용

테스트, 코드 포맷팅 등에 대한 정보로 활용한다. 대표적으로는 코드 포맷팅 도구인 black, 테스트용 프레임워크인 pytest 등이 pyproject.toml에 설정 값을 저장하고 있다 - 파이썬 패키징의 역사, blog

1
2
3
4
5
# pyproject.toml of black
[tool.black]
line-length = 88
target-version = ['py36', 'py37', 'py38']
include = '\.pyi?$'

다음

이후에 다른 빌드 도구들, 테스트 도구들을 다뤄보자.

참고

  1. 파이썬 모듈 배포하기, python.org
  2. Tool recommendations, python.org
    1. 주요 패키징에 필요한 도구 안내
  3. 파이썬 패키징의 역사, blog
  4. TOML의 이해와 기본 활용, itworld
  5. Python package의 build frontend 와 backend