github action 컴파일 (JOSS 논문)

 파이썬 라이브러리 개발을 진행하고, 라이브러리 전용 저널인 JOSS에 논문을 제출하기 위해 github action을 사용해서 컴파일 테스트를 수행해보는 과정이 필요했습니다. 본 글에서는 github action으로 md 파일과 bib 파일을 사용해서 joss 논문 컴파일을 진행했던 과정을 정리합니다. 

 

 

 다음의 JOSS 공식 문서의 글을 보며 진행하였습니다. 

Submitting a paper to JOSS [ 공식 문서 ]

Submitting a paper to JOSS — JOSS documentation

 

 

 

1. Joss paper 준비 

 먼저 개발한 라이브러리를 md파일로 작성합니다. 가장 중요한 점은 논문 상단에 제목, 태그, 저자 등의 정보를 기입해야 합니다. bibliography 부분에는 참고문헌을 정리한 bib 파일의 경로를 작성해주어야 합니다. bib 파일을 사용한 참고문헌 작성법은 밑에서 설명하겠습니다. 

 

다음은 공식문서에 나와있는 md 파일 예시의 일부입니다.

paper.md 파일 예시

---
title: 'Gala: A Python package for galactic dynamics'
tags:
  - Python
  - astronomy
  - dynamics
  - galactic dynamics
  - milky way
authors:
  - name: Adrian M. Price-Whelan
    orcid: 0000-0000-0000-0000
    equal-contrib: true
    affiliation: "1, 2" # (Multiple affiliations must be quoted)
  - name: Author Without ORCID
    equal-contrib: true # (This is how you can denote equal contributions between multiple authors)
    affiliation: 2
  - name: Author with no affiliation
    corresponding: true # (This is how to denote the corresponding author)
    affiliation: 3
affiliations:
 - name: Lyman Spitzer, Jr. Fellow, Princeton University, USA
   index: 1
 - name: Institution Name, Country
   index: 2
 - name: Independent Researcher, Country
   index: 3
date: 13 August 2017
bibliography: paper.bib

# Optional fields if submitting to a AAS journal too, see this blog post:
# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing
aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it.
aas-journal: Astrophysical Journal <- The name of the AAS journal.
---

# Summary

The forces on stars, galaxies, and dark matter under external gravitational
fields lead to the dynamical evolution of structures in the universe. The orbits
of these bodies are therefore key to understanding the formation, history, and
future state of galaxies. The field of "galactic dynamics," which aims to model
the gravitating components of galaxies to study their structure and evolution,
is now well-established, commonly taught, and frequently used in astronomy.
Aside from toy problems and demonstrations, the majority of problems require
efficient numerical tools, many of which require the same base code (e.g., for
performing numerical orbit integration).

# Statement of need

`Gala` is an Astropy-affiliated Python package for galactic dynamics. Python
enables wrapping low-level languages (e.g., C) for speed without losing
flexibility or ease-of-use in the user-interface. The API for `Gala` was
designed to provide a class-based and user-friendly interface to fast (C or
Cython-optimized) implementations of common operations such as gravitational
potential and force evaluation, orbit integration, dynamical transformations,
and chaos indicators for nonlinear dynamics. `Gala` also relies heavily on and
interfaces well with the implementations of physical units and astronomical
coordinate systems in the `Astropy` package [@astropy] (`astropy.units` and
`astropy.coordinates`).

 

 

 

paper.bib 파일 예시 

 위의 md 파일에서 bibliography 부분에 적어줘야 하는 파일입니다. 안의 내용은 BibTex 형식으로 넣어주어야 합니다. 

 

BibTex 형식은 google scholar를 예로 들어,  인용페이지 하단이 BibTex 버튼이 있습니다.  

 

해당 버튼을 누르면 아래와 같이 BibTeX 형식을 얻을 수 있습니다. 

 다음은 공식문서에 나와있는 bib 파일 예시의 일부입니다.

@article{astropy,
    author = {{Astropy Collaboration}},
    title = "{Astropy: A community Python package for astronomy}",
    journal = {Astronomy and Astrophysics},
    archivePrefix = "arXiv",
    eprint = {1307.6212},
    primaryClass = "astro-ph.IM",
    keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools},
    year = 2013,
    month = oct,
    volume = 558,
    doi = {10.1051/0004-6361/201322068},
    url = {http://adsabs.harvard.edu/abs/2013A%26A...558A..33A}
}

 가장 첫번째에 적혀있는 astropy가 참고문헌을 구분하는 문구이며, 위에 md 파일에서 

 

`Gala` also relies heavily on and interfaces well with the implementations of physical units and astronomical coordinate systems in the `Astropy` package [@astropy] 

 위의 예시처럼 인용하고 싶은 부분에 [@astropy] 와 같이 작성해주면 됩니다.

 

 

 

 

2. Github Action

 md 파일과 bib 파일이 모두 준비되었다면 github action으로 컴파일을 시도할 수 있습니다. 

 

다음의 공식문서를 참고하여 진행하였습니다. 

Open Journals PDF Generator

Open Journals PDF Generator - GitHub Marketplace

 

 

 

 .github/workflows/draft-pdf.yml  파일 생성

on: [push]

jobs:
  paper:
    runs-on: ubuntu-latest
    name: Paper Draft
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Build draft PDF
        uses: openjournals/openjournals-draft-action@master
        with:
          journal: joss
          # This should be the path to the paper within your repo.
          paper-path: paper.md
      - name: Upload
        uses: actions/upload-artifact@v1
        with:
          name: paper
          # This is the output path where Pandoc will write the compiled
          # PDF. Note, this should be the same directory as the input
          # paper.md
          path: paper.pdf

journal: joss 또는 jose 
paper-path: paper.md 의 경로 

  github 저장소에서 .github/workflows/ 의 경로에 draft-pdf.yml 파일을 하나 생성해줍니다. journal과 paper-path 만 사용자가 직접 설정해주면 됩니다. 

 

 

 

paper.pdf 확인 

  그 다음 Actions 탭에 들어가고, workflow 들 중 최신 workflow를 클릭하여 들어갑니다. 

 

 그럼 하단에 paper가 정상적으로 생성된 것을 확인할 수 있습니다. Artifacts에서 paper를 클릭하면 pdf가 들어있는 zip 파일을 다운받을 수 있습니다.