{"id":3607,"date":"2017-02-17T10:36:24","date_gmt":"2017-02-17T15:36:24","guid":{"rendered":"http:\/\/fgiasson.com\/blog\/?p=3607"},"modified":"2017-02-17T11:12:36","modified_gmt":"2017-02-17T16:12:36","slug":"literate-clojure-programming-publishing-documentation-in-multiple-formats","status":"publish","type":"post","link":"https:\/\/fgiasson.com\/blog\/index.php\/2017\/02\/17\/literate-clojure-programming-publishing-documentation-in-multiple-formats\/","title":{"rendered":"Literate [Clojure] Programming: Publishing Documentation In Multiple Formats"},"content":{"rendered":"

This blog post is the sixth, and the last, of a series of blog posts about Literate [Clojure] Programming in Org-mode<\/a> where I explain how I develop my [Clojure] applications using literate programming concepts and principles.<\/p>\n

This last post introduce a tool that leverage the side effect of having all the codes neatly discussed: it gives the possibility to automatically generate all different kinds of project documentation with a single key-binding. The documentation that we will generate are:<\/p>\n

    \n
  1. Human readable HTML general project documentation<\/li>\n
  2. Programming API documentation<\/li>\n
  3. Book style complete project documentation in PDF<\/li>\n<\/ol>\n

    This series of blog posts about literate [Clojure] programming in Org-mode is composed of the following articles:<\/p>\n

      \n
    1. Configuring Emacs for Org-mode<\/a><\/li>\n
    2. Project folder structure<\/a><\/li>\n
    3. Anatomy of a Org-mode file<\/a><\/li>\n
    4. Tangling all project files<\/a><\/li>\n
    5. Publishing documentation in multiple formats<\/a> (this post)<\/li>\n
    6. Unit Testing<\/a><\/li>\n<\/ol>\n

      <\/p>\n

      \n

      Documentation, Documentation, Documentation!<\/h2>\n
      \n

      Not all documentation is equal and depending on what you are looking for, different kinds and different formats of documentation may work better depending on a task. If I want to read in depth the architecture of a project, if I want to understand the underlying assumptions and decisions that lead to a certain design, if I want to read text with figures about data structures I would prefer reading article like documentation in form of a HTML page or a PDF document.<\/p>\n

      However, if I am programing something using a certain API, what I will be looking for is the documentation of the API with maybe some supporting material as required. I will be looking to understand how a specific function works, how its parameters are meant to be used, etc. I may also simply be looking for a consolidated list of available function calls. That kind of documentation is quite different than the previous one.<\/p>\n

      The beauty of Literate Programming is that as a software developed, I don’t have to write each of these types of documentation independently. I have everything I need in my literate programming files (in this case, in my Org-mode files) to generate all kinds of different purposes documentation.<\/p>\n

      Note that everything that is discussed in this series of blog posts has been applied to the org-mode-tests-utils<\/a> project. I would strongly suggest you to browse that project along with its folder structure to see how this works in a real [tiny] project.<\/p>\n

      Now, let’s see how this can be accomplished.<\/p>\n<\/div>\n<\/div>\n

      \n

      publish.org<\/h2>\n
      \n

      What we want to do to generate all the different kinds of documentation is simply having to open a Org-mode file, and to click C-c C-v t<\/code> which will run all the code blocks in the file that will generate all the documentation we want. That file is called publish.org<\/a> and is located in the \/org\/<\/code> root folder.<\/p>\n

      This file is split into three general sections:<\/p>\n

        \n
      1. Generate HTML Documentation<\/li>\n
      2. Generate API Documentation<\/li>\n
      3. Generate PDF Documentation<\/li>\n<\/ol>\n

        Each of these sections contains the ELisp code blocks that are used to generate the different kind of documentation.<\/p>\n<\/div>\n

        \n

        Generate HTML Documentation<\/h3>\n
        \n

        What the HTML documentation generator does is to search and find [recursively] all the .org<\/code> files that exists in the \/org\/<\/code> folder of your project. Then it will generate a sitemap.org<\/code> file if it is not already existing that it will use to generate the HTML documentation.<\/p>\n<\/div>\n

        \n

        Themes<\/h4>\n
        \n

        Different themes and styles can be defined for the generated HTML pages. To enable a theme, you simply have to select the proper :html-head<\/code> setting.<\/p>\n

        The main themes come from the org-html-themes<\/a> extension. The theme currently being used is called readtheorg<\/code>.<\/p>\n<\/div>\n<\/div>\n

        \n

        Publishing Options<\/h4>\n
        \n

        A series of settings can be configured to create the documentation the way you want. Here are the main settings:<\/p>\n