forked from nudt_dsp/netrans
249 lines
12 KiB
HTML
249 lines
12 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="zh" data-content_root="./">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<title>gen api html & pdf by sphinx — netrans 0.1 文档</title>
|
||
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=5ecbeea2" />
|
||
<link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
|
||
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=27fed22d" />
|
||
<script src="_static/documentation_options.js?v=52efc512"></script>
|
||
<script src="_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
<link rel="index" title="索引" href="genindex.html" />
|
||
<link rel="search" title="搜索" href="search.html" />
|
||
<link rel="next" title="netrans_py" href="modules.html" />
|
||
<link rel="prev" title="附录" href="appendix.html" />
|
||
|
||
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
|
||
|
||
|
||
|
||
|
||
|
||
</head><body>
|
||
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
|
||
|
||
<div class="body" role="main">
|
||
|
||
<section id="gen-api-html-pdf-by-sphinx">
|
||
<h1>gen api html & pdf by sphinx<a class="headerlink" href="#gen-api-html-pdf-by-sphinx" title="Link to this heading">¶</a></h1>
|
||
<p>netrans 目录结构如下</p>
|
||
<div class="highlight-tree notranslate"><div class="highlight"><pre><span></span>netrans/
|
||
│
|
||
├── docs/ # Sphinx 项目的根目录
|
||
│ ├── source/ # 源文件目录
|
||
│ │ ├── _static/ # 静态文件（如图片、CSS、JS）
|
||
│ │ ├── _templates/ # 自定义模板
|
||
│ │ ├── conf.py # 配置文件
|
||
│ │ ├── index.rst # 主页文件
|
||
│ │ └── my_module.rst # 其他文档文件
|
||
│ └── build/ # 构建输出目录（生成的 HTML 文件等）
|
||
│
|
||
└── bin/
|
||
└── netrans_cli/
|
||
└── netrans_py/
|
||
</pre></div>
|
||
</div>
|
||
<ol class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">sphinx-quickstart</span> <span class="pre">docs/</span></code> 快速生成</p></li>
|
||
<li><p>修改 <code class="docutils literal notranslate"><span class="pre">docs/source/conf.py</span></code> ,</p></li>
|
||
</ol>
|
||
<section id="rst">
|
||
<h2>*.rst<a class="headerlink" href="#rst" title="Link to this heading">¶</a></h2>
|
||
<p>rst, reStructuredText 文件，用于定义文档的结构。通常放在source目录下。</p>
|
||
<p>rst 是一种和 markdown 类似的语法</p>
|
||
<p>使用目录树指令 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">toctree::</span></code>，列出其他文档文件。</p>
|
||
</section>
|
||
<section id="autodoc-sphinx-python-api-html">
|
||
<h2>使用 autodoc + Sphinx 实现 python api 文档(html)<a class="headerlink" href="#autodoc-sphinx-python-api-html" title="Link to this heading">¶</a></h2>
|
||
<ol class="simple">
|
||
<li><p>修改 docs/source/conf.py</p></li>
|
||
</ol>
|
||
<div class="highlight-py3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Configuration file for the Sphinx documentation builder.</span>
|
||
<span class="c1">#</span>
|
||
<span class="c1"># For the full list of built-in configuration values, see the documentation:</span>
|
||
<span class="c1"># https://www.sphinx-doc.org/en/master/usage/configuration.html</span>
|
||
|
||
<span class="c1"># -- Project information -----------------------------------------------------</span>
|
||
<span class="c1"># https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information</span>
|
||
|
||
<span class="n">project</span> <span class="o">=</span> <span class="s1">'netrans'</span>
|
||
<span class="n">copyright</span> <span class="o">=</span> <span class="s1">'2025, ccyh'</span>
|
||
<span class="n">author</span> <span class="o">=</span> <span class="s1">'xj'</span>
|
||
<span class="n">release</span> <span class="o">=</span> <span class="s1">'0.1'</span>
|
||
|
||
<span class="c1"># -- General configuration ---------------------------------------------------</span>
|
||
<span class="c1"># https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration</span>
|
||
|
||
<span class="kn">import</span><span class="w"> </span><span class="nn">os</span>
|
||
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
|
||
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">'../../netrans_py/'</span><span class="p">)</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">'../../'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Sphinx 扩展</span>
|
||
<span class="n">extensions</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="s1">'sphinx.ext.autodoc'</span><span class="p">,</span> <span class="c1"># 自动生成文档</span>
|
||
<span class="s1">'sphinx.ext.viewcode'</span><span class="p">,</span> <span class="c1"># 添加源代码链接</span>
|
||
<span class="s1">'sphinx.ext.napoleon'</span><span class="p">,</span> <span class="c1"># 支持 NumPy 和 Google 风格的 docstring</span>
|
||
<span class="p">]</span>
|
||
|
||
<span class="c1"># 主题</span>
|
||
<span class="n">html_theme</span> <span class="o">=</span> <span class="s1">'sphinx_rtd_theme'</span>
|
||
|
||
<span class="n">templates_path</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'_templates'</span><span class="p">]</span>
|
||
<span class="n">exclude_patterns</span> <span class="o">=</span> <span class="p">[]</span>
|
||
|
||
<span class="n">language</span> <span class="o">=</span> <span class="s1">'zh'</span>
|
||
|
||
<span class="c1"># -- Options for HTML output -------------------------------------------------</span>
|
||
<span class="c1"># https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output</span>
|
||
|
||
<span class="n">html_theme</span> <span class="o">=</span> <span class="s1">'alabaster'</span>
|
||
<span class="n">html_static_path</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'_static'</span><span class="p">]</span>
|
||
|
||
<span class="n">source_suffix</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="s1">'.rst'</span><span class="p">:</span> <span class="s1">'restructuredtext'</span><span class="p">,</span>
|
||
<span class="s1">'.md'</span><span class="p">:</span> <span class="s1">'markdown'</span><span class="p">,</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<ol class="simple">
|
||
<li><p>sphinx-apidoc -o docs/source/ .
|
||
生成 netrans_py 下所有的 *.py 的rst, 并添加到index.rst里.</p></li>
|
||
</ol>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># index.rst
|
||
</pre></div>
|
||
</div>
|
||
<ol class="simple">
|
||
<li><p>sphinx-build -b html docs/source docs/build</p></li>
|
||
</ol>
|
||
</section>
|
||
<section id="autodoc-sphinx-python-api-pdf">
|
||
<h2>使用 autodoc + Sphinx 实现 python api 文档(pdf)<a class="headerlink" href="#autodoc-sphinx-python-api-pdf" title="Link to this heading">¶</a></h2>
|
||
<ol class="simple">
|
||
<li><p>在可以生成 html的 基础上, 使用make latexodf 生成 *.tex文件.
|
||
这一步会报错,原因是无法识别中文</p></li>
|
||
</ol>
|
||
<p>2.修改 netrans.tex文件</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">build</span><span class="o">/</span><span class="n">latex</span>
|
||
<span class="n">vim</span> <span class="n">netrans</span><span class="o">.</span><span class="n">tex</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在各种usapackage的地方新增:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>\<span class="n">usepackage</span><span class="p">[</span><span class="n">UTF8</span><span class="p">,</span> <span class="n">fontset</span><span class="o">=</span><span class="n">ubuntu</span><span class="p">]{</span><span class="n">ctex</span><span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<ol class="simple">
|
||
<li><p>使用 xelatex 生成pdf
|
||
sphinx使用的是 xelatex 而非 pdflatex</p></li>
|
||
</ol>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">xelatex</span> <span class="n">netrans</span><span class="o">.</span><span class="n">tex</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="id1">
|
||
<h2>常见报错<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h2>
|
||
<p>报错</p>
|
||
<div class="highlight-log notranslate"><div class="highlight"><pre><span></span>sphinx-quickstart
|
||
Traceback (most recent call last):
|
||
File "/home/xj/app/miniforge3/envs/sphinx/bin/sphinx-quickstart", line 8, in <module>
|
||
sys.exit(main())
|
||
File "/home/xj/app/miniforge3/envs/sphinx/lib/python3.10/site-packages/sphinx/cmd/quickstart.py", line 721, in main
|
||
locale.setlocale(locale.LC_ALL, '')
|
||
File "/home/xj/app/miniforge3/envs/sphinx/lib/python3.10/locale.py", line 620, in setlocale
|
||
return _setlocale(category, locale)
|
||
locale.Error: unsupported locale setting
|
||
</pre></div>
|
||
</div>
|
||
<p>解决:
|
||
export LC_ALL=en_US.UTF-8</p>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h1 class="logo"><a href="index.html">netrans</a></h1>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<search id="searchbox" style="display: none" role="search">
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
|
||
<input type="submit" value="提交" />
|
||
</form>
|
||
</div>
|
||
</search>
|
||
<script>document.getElementById('searchbox').style.display = "block"</script><h3>导航</h3>
|
||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||
<ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="quick_start_guide.html">快速入门</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="netrans_cli.html">netrans_cli 使用</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="netrans_py.html">netrans_py 使用</a></li>
|
||
<li class="toctree-l1 current"><a class="reference internal" href="appendix.html">附录</a><ul class="current">
|
||
<li class="toctree-l2 current"><a class="current reference internal" href="#">gen api html & pdf by sphinx</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="modules.html">netrans_py</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<div class="relations">
|
||
<h3>Related Topics</h3>
|
||
<ul>
|
||
<li><a href="index.html">Documentation overview</a><ul>
|
||
<li><a href="appendix.html">附录</a><ul>
|
||
<li>Previous: <a href="appendix.html" title="上一章">附录</a></li>
|
||
<li>Next: <a href="modules.html" title="下一章">netrans_py</a></li>
|
||
</ul></li>
|
||
</ul></li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="footer">
|
||
©2025, ccyh.
|
||
|
||
|
|
||
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
|
||
& <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
|
||
|
||
|
|
||
<a href="_sources/gen_api.md.txt"
|
||
rel="nofollow">Page source</a>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
</body>
|
||
</html> |