最新消息:20210816 当前crifan.com域名已被污染,为防止失联,请关注(页面右下角的)公众号

【已解决】Gitbook中把README整理出模板便于统一修改说明内容

gitbook crifan 1638浏览 0评论

之前用Gitbook去发布自己的ebook电子书教程。

对于电子书入口介绍的文档,典型的都是README.md文件,比如:

如果某个单本book的README.md需要修改,则单独去修改即可。

后来由于电子书逐渐增多,已有几十个:

而偶尔会遇到:

需要统一,全部,一次性,修改所有的电子书的README.md的内容,则:

目前只能手动一个个的去修改,效率很低。

所以考虑:

把README.md去做成模板,然后每个Gitbook的ebook去导入即可。

类似于之前的:

crifan/gitbook_template: 演示如何使用crifan的gitbook的模板去创建自己的gitbook电子书

中的:book.json的逻辑:

然后此处希望实现:

  • 模板:弄个REAME.md的模板

  • 目前考虑用json格式,比如:

  • REAME_template.json

  • 每本book:有自己的 README_current.md

  • 然后去写脚本 ,或者找到合适的模板工具或语言,能够合并生成

  • 每本book自己的:README.md

  • 现在问题就剩:

    • 设计一个好用的REAME_template.json

    • 找到合适的模板语言或自己写python脚本去合并处理

    • 如果是自己写python脚本合并处理

    • 都能想到,最简单,最通用的逻辑是:

    • template中定义{{field_name}}

    • 然后python中去替换 {{field_name}} 为 json中定义的

    • { “field_name”: field_value}

    • 的 field_value

  • 好像就够用了?无需额外的繁琐

  • 先去找找,是否有合适的模板语言和工具

    模板生成 python

    Python 利用 Jinja2 模版生成文件 | hoxis’ blog

    可以考虑用Jinja2

    但是貌似很麻烦,还要有额外的__init__.py等文件

    Python使用模板自动生成代码 – 南阳人的个人空间 – OSCHINA

    python实现的模板生成脚本 – 上帝De助手 – CSDN博客

    算了,还是自己写代码去处理和替换吧

    用如下代码:

    generateREADME.py

    #!/usr/bin/python
    # -*- coding: utf-8 -*-
    """
    Author: Crifan Li
    Version: v1.0 20190515
    Function: Generate Gitbook's README.md from ../README_template.md and README_current.json
    Note: should run this python file from single gitbook foler
          eg: /Users/crifan/dev/dev_root/gitbook/gitbook_src_root/gitbook_demo
    """
    

    import os

    import json

    import codecs

    import re

    ################################################################################

    # Global Config

    ################################################################################

    gReadmeTemplateFilename = “README_template.md”

    gReadmeCurrentFilename = “README_current.json”

    # gReadmeOutputFilename = “README.md”

    # for debug

    gReadmeOutputFilename = “README_tmp_generated.md”

    ################################################################################

    # Internal Function

    ################################################################################

    def loadTextFromFile(fullFilename, fileEncoding=”utf-8″):

        “””load file text content from file”””

        with codecs.open(fullFilename, ‘r’, encoding=fileEncoding) as fp:

            allText = fp.read()

            # logging.debug(“Complete load text from %s”, fullFilename)

            return allText

    def saveTextToFile(fullFilename, textData):

        “””save text data info file”””

        with open(fullFilename, ‘w’) as fp:

            fp.write(textData)

            fp.close()

            print(“Complete save file %s” % fullFilename)

    def loadJsonFromFile(fullFilename):

        “””load and parse json dict from file”””

        jsonDict = {}

        with codecs.open(fullFilename, ‘r’, encoding=”utf-8″) as jsonFp:

            try:

                jsonDict = json.load(jsonFp)

                print(“Complete load json from %s” % fullFilename)

            except json.decoder.JSONDecodeError as decodeError:

                print(“JSONDecodeError %s for %s” % (decodeError, fullFilename))

                jsonDict = None

        return jsonDict

    ################################################################################

    # Main Part

    ################################################################################

    def generateReadmeMd():

      # run python in :

      # /Users/crifan/dev/dev_root/gitbook/gitbook_src_root/gitbook_demo

      curBookPath = os.getcwd()

      # for debug

      curBookPath = “/Users/crifan/dev/dev_root/gitbook/gitbook_src_root/gitbook_demo”

      # curBookPath = “/Users/crifan/dev/dev_root/gitbook/gitbook_src_root/all_age_sports_badminton”

      print(“curBookPath=%s” % curBookPath)

      # /Users/crifan/dev/dev_root/gitbook/gitbook_src_root/gitbook_demo

      curDirname = os.path.dirname(curBookPath)

      print(“curDirname=%s” % curDirname)

      # /Users/crifan/dev/dev_root/gitbook/gitbook_src_root

      curBasename = os.path.basename(curBookPath)

      print(“curBasename=%s” % curBasename)

      # gitbook_demo

      bookRootPath = curDirname

      print(“bookRootPath=%s” % bookRootPath)

      # /Users/crifan/dev/dev_root/gitbook/gitbook_src_root

      readmeTemplateFulPath = os.path.join(bookRootPath, gReadmeTemplateFilename)

      print(“readmeTemplateFulPath=%s” % readmeTemplateFulPath)

      readmeTemplateMdStr = loadTextFromFile(readmeTemplateFulPath)

      print(“readmeTemplateMdStr=%s” % readmeTemplateMdStr)

      readmeCurrentFullPath = os.path.join(curBookPath, gReadmeCurrentFilename)

      print(“readmeCurrentFullPath=%s” % readmeCurrentFullPath)

      readmeCurrentJson = loadJsonFromFile(readmeCurrentFullPath)

      print(“readmeCurrentJson=%s” % readmeCurrentJson)

      for eachKey in readmeCurrentJson.keys():

        print(“eachKey=%s” % eachKey)

        patternToReplace = “\{\{%s\}\}” % eachKey

        replacedStr = readmeCurrentJson[eachKey]

        print(“patternToReplace=%s -> replacedStr=%s” % (patternToReplace, replacedStr))

        readmeTemplateMdStr = re.sub(patternToReplace, replacedStr, readmeTemplateMdStr)

        print(“readmeTemplateMdStr=%s” % readmeTemplateMdStr)

      

      generatedReadmeFullPath = os.path.join(curBookPath, gReadmeOutputFilename)

      print(“generatedReadmeFullPath=%s” % generatedReadmeFullPath)

      saveTextToFile(generatedReadmeFullPath, readmeTemplateMdStr)

    if __name__ == “__main__”:

        generateReadmeMd()

    和配套文件:

    /Users/crifan/dev/dev_root/gitbook/gitbook_src_root/README_template.md

    # {{bookName}}
    
    

    * 最新版本:`{{latestVersion}}`

    * 更新时间:`{{lastUpdate}}`

    ## 鸣谢

    感谢我的老婆**陈雪雪**的包容理解和悉心照料,才使得我`crifan`有更多精力去专注技术专研和整理归纳出这些电子书和技术教程,特此鸣谢。

    ## 简介

    {{bookDescription}}

    ## 源码+浏览+下载

    本书的各种源码、在线浏览地址、多种格式文件下载如下:

    ### Gitbook源码

    * [crifan/{{gitRepoName}}: {{bookName}}](https://github.com/crifan/{{gitRepoName}})

    #### 如何使用此Gitbook源码去生成发布为电子书

    详见:[crifan/gitbook_template: demo how to use crifan gitbook template and demo](https://github.com/crifan/gitbook_template)

    ### 在线浏览

    * [{{bookName}} book.crifan.com](http://book.crifan.com/books/{{gitRepoName}}/website)

    * [{{bookName}} crifan.github.io](https://crifan.github.io/{{gitRepoName}}/website)

    ### 离线下载阅读

    * [{{bookName}} PDF](http://book.crifan.com/books/{{gitRepoName}}/pdf/{{gitRepoName}}.pdf)

    * [{{bookName}} ePub](http://book.crifan.com/books/{{gitRepoName}}/epub/{{gitRepoName}}.epub)

    * [{{bookName}} Mobi](http://book.crifan.com/books/{{gitRepoName}}/mobi/{{gitRepoName}}.mobi)

    /Users/crifan/dev/dev_root/gitbook/gitbook_src_root/gitbook_demo/README_current.json

    {
      "latestVersion": "v1.0",
      "lastUpdate": "20190515",
      "gitRepoName": "gitbook_demo",
      "bookName": "Gitbook演示",
      "bookDescription": "`crifan`的`Gitbook`模版,用于演示如何创建一个自己的`Gitbook`"
    }

    测试生成的README.md:

    # Gitbook演示
    * 最新版本:`v1.0`
    * 更新时间:`20190515`
    

    ## 鸣谢

    感谢我的老婆**陈雪雪**的包容理解和悉心照料,才使得我`crifan`有更多精力去专注技术专研和整理归纳出这些电子书和技术教程,特此鸣谢。

    ## 简介

    `crifan`的`Gitbook`模版,用于演示如何创建一个自己的`Gitbook`

    ## 源码+浏览+下载

    本书的各种源码、在线浏览地址、多种格式文件下载如下:

    ### Gitbook源码

    * [crifan/gitbook_demo: Gitbook演示](https://github.com/crifan/gitbook_demo)

    #### 如何使用此Gitbook源码去生成发布为电子书

    详见:[crifan/gitbook_template: demo how to use crifan gitbook template and demo](https://github.com/crifan/gitbook_template)

    ### 在线浏览

    * [Gitbook演示 book.crifan.com](http://book.crifan.com/books/gitbook_demo/website)

    * [Gitbook演示 crifan.github.io](https://crifan.github.io/gitbook_demo/website)

    ### 离线下载阅读

    * [Gitbook演示 PDF](http://book.crifan.com/books/gitbook_demo/pdf/gitbook_demo.pdf)

    * [Gitbook演示 ePub](http://book.crifan.com/books/gitbook_demo/epub/gitbook_demo.epub)

    * [Gitbook演示 Mobi](http://book.crifan.com/books/gitbook_demo/mobi/gitbook_demo.mobi)

    和之前,是一样的(除了自己新加内容之外):

    达到了我要的效果。

    然后再去把当前的处理脚本

    generateREADME.py

    后改名为:

    generateReadmeMd.py

    合并到之前的Makefile

    https://github.com/crifan/gitbook_template/blob/master/GitbookCommon.mk

    中。

    /Users/crifan/dev/dev_root/gitbook/gitbook_src_root/GitbookCommon.mk

    ## Clean generated README.md file

    clean_generated_readme_md:

        -rm -f README.md

    ## Generate README.md from ../README_template.md and README_current.json

    generate_readme_md: clean_generated_readme_md

        @python  ../generateReadmeMd.py

    ## sync content

    sync_content: generate_book_json generate_readme_md copy_readme copy_gitignore

        @echo Complete sync content

    然后:

    ➜  gitbook_demo make help
      clean_generated_readme_md Clean generated README.md file
      generate_readme_md        Generate README.md from ../README_template.md and README_current.json

    即可。

    转载请注明:在路上 » 【已解决】Gitbook中把README整理出模板便于统一修改说明内容

    发表我的评论
    取消评论

    表情

    Hi,您需要填写昵称和邮箱!

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址
    89 queries in 0.180 seconds, using 22.16MB memory