首页 > 其他分享 >Github + Sphinx+Read the docs 实战入门指南(一)

Github + Sphinx+Read the docs 实战入门指南(一)

时间:2023-04-02 15:46:43浏览次数:50  
标签:RapidVideOCR ... Github Sphinx Read html done

引言

Github
  • Github是一个托管网站,目前主要用来托管代码,当然托管其他的也可。但是网不好的小伙伴可以考虑使用Gitee作为平替。
Sphinx
  • Sphinx是什么? Sphinx是一个自动生成文档的工具,可以用简洁的语法快速生成优雅的文档。

  • 哪些场景要用Sphinx? 如果想要写书,不想陷入复杂的排版中,可以考虑使用这个。如果有代码项目之类的,可以用它快速生成使用文档,支持markdown语法。

Readthedocs
  • RTD(Read the docs) 是一个文档托管网站,这一点从网站名字上就能看出来。

  • 在与Github连接上配置无误的情况下,当Github上有文件改动时,会自动触发RTD自动更新对应的文档。RTD提供了丰富的文档主题,有着灵活的配置,可以满足大部分的需求。

  • RTD vs Github Pages:

    • Github Pages是Github下自带的静态网站托管服务,选择合适主题后,也可根据Github的内容,自动排版和更新对应内容到网站中。之前搭建过一个,感兴趣可以去AI比赛经验帖子集锦。下图是缩略图: !

    66e49a154cc84605aa5607eb9b462b03.png

    • 选择RTD的理由是什么呢? 对于我来说,有一点是最主要的:RTD可以做多版本文档的显示。当在Github仓库Release时,RTD网站也会出对应一版的文档,可以自己来选择是否激活。类似下图。而其他功能,两者都差不多。(仅一家之言)

8a9e83f5a9a2422c9ba721241e11ef3d.png

部署前环境情况

  • 自己的Github 代码仓库(本文以RapidVideOCR为例)
  • 注册好的Read the docs账号,注册地址:注册

搭建步骤

Note:请静下心来,一步一步地来。

一、本地搭建Sphinx环境,用于本地查看效果
  1. 克隆远程Github仓库到本地:git clone [email protected]:SWHL/RapidVideOCR.git
  2. 安装python和pip(这个请自行百度,假设已经安装好)
  3. 安装sphinx: pip install sphinx
  4. 基于RaidVideOCR创建sphinx项目工程,命令执行情况如下:
    (demo) PS G:\ProgramFiles\_self\RapidVideOCR> sphinx-quickstart
    Welcome to the Sphinx 5.3.0 quickstart utility.
    
    Please enter values for the following settings (just press Enter to
    accept a default value, if one is given in brackets).
    
    Selected root path: .
    
    You have two options for placing the build directory for Sphinx output.
    Either, you use a directory "_build" within the root path, or you separate
    "source" and "build" directories within the root path.
    > Separate source and build directories (y/n) [n]: y
    
    The project name will occur in several places in the built documentation.
    > Project name: RapidVideOCR
    > Author name(s): SWHL
    > Project release []: v2.1.6
    
    If the documents are to be written in a language other than English,
    you can select a language here by its language code. Sphinx will then
    translate text that it generates into that language.
    
    For a list of supported codes, see
    https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
    > Project language [en]: zh_CN
    
    Creating file G:\ProgramFiles\_self\RapidVideOCR\source\conf.py.
    Creating file G:\ProgramFiles\_self\RapidVideOCR\source\index.rst.
    Creating file G:\ProgramFiles\_self\RapidVideOCR\Makefile.
    Creating file G:\ProgramFiles\_self\RapidVideOCR\make.bat.
    
    Finished: An initial directory structure has been created.
    
    You should now populate your master file G:\ProgramFiles\_self\RapidVideOCR\source\index.rst and create other documentation
    source files. Use the Makefile to build the docs, like so:
       make builder
    where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
    
  5. 最终文件目录结构:
    RapidVideOCR
    ├── build  # 生成的文件的输出目录
    ├── LICENSE
    ├── make.bat  # Windows 命令行中编译用的脚本
    ├── Makefile  # 编译脚本,make 命令编译时用
    ├── rapid_videocr
    ├── README.md
    ├── requirements.txt
    ├── setup.py
    ├── source  # 存放文档源文件
    │   ├── conf.py  # 进行 Sphinx 的配置,如主题配置等
    │   ├── index.rst  # 文档项目起始文件,用于配置文档的显示结构
    │   ├── _static  # 静态文件目录,比如图片等
    │   └── _templates  # 模板目录
    └── tests
    
  6. 生成最原始的文档文件:
     (demo) PS G:\ProgramFiles\_self\RapidVideOCR> make html
     Running Sphinx v5.3.0
     loading translations [zh_CN]... done
     making output directory... done
     building [mo]: targets for 0 po files that are out of date
     building [html]: targets for 1 source files that are out of date
     updating environment: [new config] 1 added, 0 changed, 0 removed
     reading sources... [100%] index
     looking for now-outdated files... none found
     pickling environment... done
     checking consistency... done
     preparing documents... done
     writing output... [100%] index
     generating indices... genindex done
     writing additional pages... search done
     copying static files... done
     copying extra files... done
     dumping search index in Chinese (code: zh)... done
     dumping object inventory... done
     build succeeded.
     
     The HTML pages are in build\html.
     (demo) PS G:\ProgramFiles\_self\RapidVideOCR> 
    
  7. 查看效果
    • 打开RapidVideOCR目录下的build/html,双击打开index.html
      build
      ├── doctrees
      │   ├── environment.pickle
      │   └── index.doctree
      └── html
          ├── genindex.html
          ├── index.html  # 双击打开这个
          ├── objects.inv
          ├── search.html
          ├── searchindex.js
          ├── _sources
          └── _static
      
    • 效果如下图所示:
      在这里插入图片描述
  • 至此,本地最基本的Spinx文档系统搭建已经完成。

二、定制化部分

说明:定制化的配置都在source/conf.py中设置。因为有一些额外需求,因此需要定制化。

  1. 更改样式主题。我这里以sphinx_rtd_theme为例子,其他主题可自行百度。

    • 安装sphinx_rtd_theme: pip install sphinx_rtd_theme
  2. 安装markdown语法支持插件:pip install myst-parser

  3. 安装支持mermaid渲染插件: pip install sphinxcontrib.mermaid

    ```{mermaid}  # 注意这里需要{}包裹
    graph LR
      a --> b
    ```
    
  4. 安装代码块一键复制按钮插件:pip install sphinx_copybutton

  5. 最后配置conf.py如下,

    project = 'RapidVideOCR'
    copyright = '2023, SWHL'
    author = 'SWHL'
    release = 'v2.1.6'
        
    extensions = [
        'myst_parser',
        "sphinxcontrib.mermaid",
        "sphinx_copybutton",
    ]
    
    source_suffix = {
        '.rst': 'restructuredtext',
        '.txt': 'markdown',
        '.md': 'markdown',
    }
    
    myst_enable_extensions = [
        "tasklist",
        "deflist",
        "dollarmath",
    ]
    
    templates_path = ['_templates']
    exclude_patterns = []
    
    language = 'zh_CN'
    
    html_theme = 'sphinx_rtd_theme'
    html_theme_options = {
        'analytics_anonymize_ip': False,
        'logo_only': True,
        'display_version': True,
        'prev_next_buttons_location': 'bottom',
        'style_external_links': False,
        'collapse_navigation': True,
        'sticky_navigation': True,
        'navigation_depth': 4,
        'includehidden': True,
        'titles_only': False,
    }
    
    html_logo = "./_static/logo.png"
    html_static_path = ['_static']
    html_js_files = [
        'my_custom.js',
    ]
    
  6. my_custom.js写法(以下为示例)

    • 下面这段代码用来设置主题左上角logo的重定向到指定链接。my_custom.js位于_static目录下
      $(document).ready(function(){
          let div_logo = document.getElementsByClassName("wy-side-nav-search")[0];
          let a_logo = div_logo.getElementsByTagName("a");
          a_logo[0].href = "https://github.com/SWHL/RapidVideOCR";
          a_logo[0].target = "_blank";
      });
      
  7. 重新生成html,查看效果

    • 执行make html
      (demo) PS G:\ProgramFiles\_self\RapidVideOCR> make html
      Running Sphinx v5.3.0
      loading translations [zh_CN]... done
      loading pickled environment... done
      myst v0.18.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=['tasklist', 'deflist', 'dollarmath'], disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=None, heading_slug_func=None, footnote_transition=True, words_per_minute=200, sub_delimiters=('{', '}'), linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area')
      building [mo]: targets for 0 po files that are out of date
      building [html]: targets for 1 source files that are out of date
      updating environment: 0 added, 0 changed, 0 removed
      looking for now-outdated files... none found
      preparing documents... done
      writing output... [100%] index
      generating indices... genindex done
      writing additional pages... search done
      copying static files... done
      copying extra files... done
      dumping search index in Chinese (code: zh)... done
      dumping object inventory... done
      build succeeded.
      
      The HTML pages are in build\html.
      (demo) PS G:\ProgramFiles\_self\RapidVideOCR>
      
    • 打开build/html/index.html查看效果在这里插入图片描述
  • 至此,简单的定制化已经完毕。

继续阅读

标签:RapidVideOCR,...,Github,Sphinx,Read,html,done
From: https://www.cnblogs.com/shiwanghualuo/p/17280590.html

相关文章

  • 【webpack】TypeError: Cannot read property 'tap' of undefined
    前言项目里使用webpack的代码混淆工具webpack-obfuscator,当打包代码时,出现如下报错:TypeError:Cannotreadproperty'tap'ofundefined原因项目的webpack版是4.x,而webpack-obfuscator的版本是3.x解决方法查阅资料在该https://nodejs7.com/2021/11/27/797.html文......
  • ESPRESSIF-pip安装模板超时Read timed out
    一、问题:pip._vendor.urllib3.exceptions.ReadTimeoutError:HTTPSConnectionPool(host='files.pythonhosted.org',port=443):Readtimedout.Commandfailed:"C:\Users\zhang\.espressif\python_env\idf4.4_py3.8_env\Scripts\python.exe"-mp......
  • 类型类Type classes(第一部分)类约束 Eq、Ord、Show、Read、Enum、Num、Integral、Float
    类型类Typeclasses是一种定义某种行为的接口。如果类型是类型类的成员,则意味着类型支持并实现了类型类定义的行为。类约束==函数的类型,如下:type(==)(==)::Eqa=>a->a->Bool=>符号定义了一个类约束,==函数接受两个相同类型的形参,并返回Bool类型。这两个形参的类型......
  • AI写代码 GitHub Copilot + Idea 安装和使用教程
    GitHubCopilot是微软与OpenAI共同推出的一款AI编程工具,基于GitHub及其他网站的源代码,根据上文提示为程序员自动编写下文代码,可以极大地提高编写代码的效率。根据已有上下文补全代码根据函数名和参数,生成方法体根据注释自动生成代码代码优化生成测试代码一、GitHubCopil......
  • Visual Studio Code 1.77 发布,扩展的 GitHub Copilot 集成
    VSCode1.77已发布,此版本一些主要亮点包括:Accessibility改进 -用于悬停、通知和StickyScroll的新键盘快捷键。、down、home、end、pageup和pagedown 键来聚焦悬停控件并进行水平和垂直滚动。聚焦悬停控件的键盘快捷键(Ctrl+KCtrl+I)与用于在主光标位置显示悬停的......
  • GitHub OAuth 第三方登录示例
     ⇐  ⇒GitHubOAuth第三方登录示例教程作者:阮一峰日期:2019年4月21日这组OAuth系列教程,第一篇介绍了基本概念,第二篇介绍了获取令牌的四种方式,今天演示一个实例,如何通过OAuth获取API数据。很多网站登录时,允许使用第三方网站的身份,这称为"第三......
  • c++ 多线程编程std::thread, std::shared_mutex, std::unique_lock
    在C++11新标准中,可以简单通过使用thread库,来管理多线程,使用时需要#include<thread>头文件。简单用例如下:1std::thread(Simple_func);2std::threadt(Simple_func);3t.detach();第一行是直接启动一个新线程来执行Simple_func函数,而第二行先声明一个线程函数t(返回类型为......
  • README
    pytestcachedirectoryThisdirectorycontainsdatafromthepytest'scacheplugin,whichprovidesthe--lfand--ffoptions,aswellasthecachefixture.Donotcommitthistoversioncontrol.Seethedocsformoreinformation.......
  • 线程池----ThreadPoolExecutor
    从Java5开始,Java提供了自己的线程池。线程池就是一个线程的容器,每次只执行额定数量的线程。java.util.concurrent.ThreadPoolExecutor就是这样的线程池。它很灵活,但使用起来也比较复杂,本文就对其做一个介绍。首先是构造函数。以最简单的构造函数为例:publicThreadPoolExecuto......
  • Java并发编程——Thread详解
    前言操作系统中,一个进程往往代表着一个应用程序实例,而线程是进程中轻量级的调度单元,也可以看作是轻量级的进程,可以共享进程资源。下面简单介绍在操作系统中线程通用实现方式。接下来内容主要对线程模型进行简单介绍,然后对Java线程实现Thread类进行了解。一、线程模型暂且抛开Jav......