如何创建工件坐标系_自动创建研究工件

如何创建工件坐标系

在我作为编程语言研究人员的工作中，我需要创建易于理解和有据可查的工件 。 为了简化工作，我找到了一种简单的方法来自动生成源代码文档，创建用户文档HTML和PDF版本，将技术（研究）文档编译为PDF，生成书目以及通过软件伪像配置虚拟机为便于我的研究重现而安装。

我使用的工具是：

• 为所有组件的整体编排制作 makefile
• Haddock用于生成源代码文档
• Pandoc用于从Markdown文件生成PDF和HTML文件
• 供应虚拟机的游民
• 用于下载Haskell依赖项，编译，运行测试等的堆栈
• pdflaTeX，用于将LaTeX文件编译为PDF格式
• BibTeX用于生成书目
• 压缩以打包所有东西并准备分发

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

   
   

    
    

     
     ├── 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将上面列出的所有工具的输出粘合在一起。 代码文件夹包含我创建的工具/语言的源代码。 文档文件夹包含一个Makefile，该文件位于README.md文件中，其中包含有关如何生成用户说明的PDF和HTML版本的说明。 我使用Pandoc生成PDF和HTML用户文档。 这些资源只是要使用CSS样式，而是我的研究论文的PDF，它将从用户生成的文档中超链接，因此很容易遵循。 meta.yaml包含用于生成用户文档的元指令，该文档由Pandoc用于例如作者姓名。 研究文件夹包含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，该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），我们在这两次会议中均获得了Disguinshed Artifact Award。

翻译自: https://opensource.com/article/20/1/automating-documentation

如何创建工件坐标系