自动化研究成果的创建

一种自动化生成源代码文档、创建用户文档的 HTML 和 PDF 版本、将技术（研究）文档编译为 PDF、生成参考文献以及配置虚拟机的简单方法。

在作为编程语言研究员的工作中，我需要创建易于理解且文档完善的成果。为了让我的工作更轻松，我找到了一种简单的方法来自动化生成源代码文档、创建用户文档的 HTML 和 PDF 版本、将技术（研究）文档编译为 PDF、生成参考文献以及配置安装了软件成果的虚拟机，以便轻松重现我的研究。

我使用的工具包括

Make makefile 用于所有组件的总体编排
Haddock 用于生成源代码文档
Pandoc 用于从 Markdown 文件生成 PDF 和 HTML 文件
Vagrant 用于配置虚拟机
Stack 用于下载 Haskell 依赖项、编译、运行测试等
pdflaTeX 用于将 LaTeX 文件编译为 PDF 格式
BibTeX 用于生成参考文献
Zip 用于打包所有内容并准备好进行分发

我使用以下文件夹和文件结构

├── Makefile
├── Vagrantfile
├── code
│   └── typechecker-oopl (Project)
│       ├── Makefile
│       └── ...
│
├── documentation
│   ├── Makefile
│   ├── README.md
│   ├── assets
│   │   ├── pandoc.css (Customised CSS for Pandoc)
│   │   └── submitted-version.pdf (PDF of your research)
│   └── meta.yaml
│
├── research
│   ├── Makefile
│   ├── ACM-Reference-Format.bst
│   ├── acmart.cls
│   ├── biblio.bib
│   └── typecheckingMonad.tex

Makefile 将上面列出的所有工具的输出粘合在一起。code 文件夹包含我创建的工具/语言的源代码。documentation 文件夹包含一个 Makefile，其中包含有关如何生成用户说明的 PDF 和 HTML 版本的说明，用户说明位于 README.md 文件中。我使用 Pandoc 生成 PDF 和 HTML 用户文档。assets 只是要使用的 CSS 样式以及我的研究文章的 PDF，该 PDF 将从用户生成的文档中超链接，以便于跟踪。meta.yaml 包含用于生成用户文档的元指令，例如，Pandoc 使用它来获取作者姓名。research 文件夹包含我的 LaTeX 格式的研究文章，但它可以包含任何其他技术文档。

正如您在结构中看到的那样，我为每个文件夹都准备了一个 Makefile，以解耦每个 Makefile 的职责并保持（某种程度上）可维护的设计。以下是顶级 Makefile 的概述，它编排了用户文档、研究论文、参考文献、源代码文档以及虚拟机配置的生成。

all: doc gen

doc:
	make -C $(DOC_SRC) $@
	make -C $(CODE_PATH) $@
	make -C $(RESEARCH)

gen:
	# Creation of folder with artefact, empty at the moment
	mkdir -p $(ARTEFACT_FOLDER)

	# Moving user documentation to artefact folder
	cp $(DOC_SRC)/$(README).pdf $(ARTEFACT_FOLDER)
	cp $(DOC_SRC)/$(README).html $(ARTEFACT_FOLDER)
	cp -r $(DOC_SRC)/$(ASSETS) $(ARTEFACT_FOLDER)

	# Moving research article to artefact folder
	cp $(RESEARCH)/$(RESEARCH_PAPER).pdf $(ARTEFACT_FOLDER)/$(ASSETS)/submitted-version.pdf

	# Moving code and autogenerated doc to artefact folder
	cp -r $(CODE_PATH) $(ARTEFACT_FOLDER)
	cd $(ARTEFACT_FOLDER)/$(CODE_SRC)
	$(STACK)
	cd ../..
	rm -rf $(ARTEFACT_FOLDER)/$(DOC_SRC)
	mv $(ARTEFACT_FOLDER)/$(CODE_SRC)/$(HADDOCK) $(ARTEFACT_FOLDER)/$(DOC_SRC)

	# zip it!
	zip $(ZIP_FILE) $(ARTEFACT_FOLDER)

update:
	vagrant up
	vagrant provision

clean:
	rm -rf $(ARTEFACT_FOLDER)

.PHONY: all clean doc gen update

首先，doc 目标使用 Pandoc 生成用户文档，然后它使用 Haddock 从 Haskell 库源代码生成文档，最后，它从 LaTeX 文件创建 PDF。如下图所示，生成的用户文档采用 HTML 和 CSS 格式。用户文档包含指向生成的源代码文档（也采用 HTML 和 CSS 格式）以及技术（研究）论文的链接。生成的源代码文档直接链接到源代码，以防读者想要了解实现。

用户文档是使用以下 Makefile 生成的

DOCS=README.md
META=meta.yaml
NUMBER_SECTION_HEADINGS=-N

.PHONY: all doc clean

all: doc

doc: $(DOC)
	pandoc -s $(META) $(DOCS) --listings --pdf-engine=xelatex -c assets/pandoc.css -o $(DOCS:md=pdf)
	pandoc -s $(META) $(DOCS) --self-contained -c assets/pandoc.css -o $(DOCS:md=html)

clean:
	rm $(DOCS:md=pdf) $(DOCS:md=html)

为了从 Haskell 代码生成文档，我使用了另一个 Makefile，它使用 Stack 来编译库和下载依赖项，并使用 Haddock（在其 OPTS 或选项中）来创建 HMTL 文档

OPTS=exec -- haddock --html --hyperlinked-source --odir=docs

doc:
	stack $(OPTS) src/Initial/AST.hs src/Initial/Typechecker.hs \
	src/Reader/AST.hs src/Reader/Typechecker.hs \
	src/Backtrace/AST.hs src/Backtrace/Typechecker.hs \
	src/Warning/AST.hs src/Warning/Typechecker.hs \
	src/MultiError/AST.hs src/MultiError/Typechecker.hs \
	src/PhantomFunctors/AST.hs src/PhantomFunctors/Typechecker.hs \
	src/PhantomPhases/AST.hs src/PhantomPhases/Typechecker.hs \
	src/Applicative/AST.hs src/Applicative/Typechecker.hs \
	src/Final/AST.hs src/Final/Typechecker.hs

.PHONY: doc

我使用这个简单的 Makefile 将研究论文从 LaTeX 编译为 PDF

.PHONY: research

research:
	pdflatex typecheckingMonad.tex
	bibtex typecheckingMonad
	pdflatex typecheckingMonad.tex
	pdflatex typecheckingMonad.tex

虚拟机 (VM) 依赖于 Vagrant 和 Vagrantfile，在其中我可以编写所有命令来设置 VM。我不知道如何自动化的一件事是将所有生成的文档移动到 VM 中。如果您知道如何将文件从主机传输到 VM，请在评论中分享您的解决方案。这意味着，目前，我手动进入 VM 并将文档放在 Desktop 文件夹中。

# All Vagrant configuration is done below. The "2" in Vagrant.configure
# configures the configuration version (we support older styles for
# backwards compatibility). Please don't change it unless you know what
# you're doing.
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/trusty64"
  config.ssh.username = "vagrant"
  config.ssh.password = "vagrant"
  config.vm.provider "virtualbox" do |vb|
    # Display the VirtualBox GUI when booting the machine
    vb.gui = true

    # Customize the amount of memory on the VM:
    vb.memory = "2048"
    vb.customize ["modifyvm", :id, "--vram", "64"]
  end
  config.vm.provision "shell", inline: <<-SHELL
    ## Installing dependencies, comment after this has been done once.
    # sudo apt-get update -y
    # sudo apt-get install ubuntu-desktop -y
    # sudo apt-get install -y build-essential linux-headers-server

    # echo 'PATH="/home/vagrant/.local/bin:$PATH"' >> /home/vagrant/.profile

    ## Comment and remove the folder sharing before submission
    mkdir -p /home/vagrant/Desktop/TypeChecker
    cp -r /vagrant/artefact-submission/* /home/vagrant/Desktop/TypeChecker/
    chown -R vagrant:vagrant /home/vagrant/Desktop/TypeChecker/
  SHELL
end

完成最后一步后，一切都已连接完毕。您可以在 HTML 和 PDF 中看到一个结果示例。我创建了一个 GitHub 存储库，其中包含所有源代码，以便于学习和重现。

我已经将此设置用于两次会议——欧洲面向对象编程会议 (ECOOP) 和国际软件语言工程会议 (SLE)，我们在两次会议上都获得了杰出成果奖。

接下来阅读什么