天津 网站建设,app开发公司价格表,wordpress主题首页问题,个人个性网页界面设计3. 构建 LAMMPS
3.8.构建 LAMMPS 文档
根据您获取 LAMMPS 的方式以及您是否自己构建了手册#xff0c;该目录有许多子目录和文件。这是一个包含描述的列表#xff1a;
README # brief info about the documentation
src # content files for LAMM…3. 构建 LAMMPS
3.8.构建 LAMMPS 文档
根据您获取 LAMMPS 的方式以及您是否自己构建了手册该目录有许多子目录和文件。这是一个包含描述的列表
README # brief info about the documentation
src # content files for LAMMPS documentation
html # HTML version of the LAMMPS manual (see html/Manual.html)
utils # tools and settings for building the documentation
lammps.1 # man page for the lammps command
msi2lmp.1 # man page for the msi2lmp command
Manual.pdf # large PDF version of entire manual
LAMMPS.epub # Manual in ePUB e-book format
LAMMPS.mobi # Manual in MOBI e-book format
docenv # virtualenv folder for processing the manual sources
doctrees # temporary data from processing the manual
doxygen # doxygen configuration and output
.gitignore # list of files and folders to be ignored by git
doxygen-warn.log # logfile with warnings from running doxygen
github-development-workflow.md # notes on the LAMMPS development workflow
如果您从 LAMMPS 网站下载 LAMMPS 作为 tarball则应包含 html 文件夹和 PDF 文件。
如果您从公共 git 存储库下载 LAMMPS则不包含 HTML 和 PDF 文件。您可以通过在 doc 文件夹中键入 make html 或 make pdf 自行构建 HTML 或 PDF 文件。这需要各种工具和文件。其中一些必须安装见下文。对于其余部分构建过程将尝试下载并将它们安装到 python 虚拟环境和本地文件夹中。
该手册的当前版本最新功能版本即发布分支的状态可在线获取https://docs.lammps.org/。与正在进行的开发即开发分支的状态相对应的手册版本可在线获取https://docs.lammps.org/latest/ 与最新稳定的 LAMMPS 版本相对应的手册版本这是稳定分支的状态可在线获取https://docs.lammps.org/stable/
3.8.1.使用 GNU make 构建
LAMMPS 手册以 reStructuredText 格式编写可以使用 Sphinx 文档生成器工具将其转换为不同的输出格式。它还包含通过 Doxygen 程序从 LAMMPS C 源代码中提取的程序员文档。目前支持翻译为 HTML、PDF通过 LaTeX、ePUB对于许多电子书阅读器和 MOBI对于 Amazon Kindle 阅读器。为了使 Python 解释器版本 3.8 或更高版本正常工作需要 doxygen 工具以及用于下载其他文件和工具的 Internet 访问权限。通常仅需要一次或在使用 make clean-all 将文档文件夹返回到原始状态后才需要进行此下载。
对于文档构建在文件夹 doc/docenv 中设置了 python 虚拟环境并通过 pip 工具将各种 python 包安装到该虚拟环境中。为了渲染嵌入式 LaTeX 代码还需要下载 MathJax JavaScript 引擎。如果您需要将其他选项传递给 pip 命令才能工作例如使用 Web 代理或指向其他 SSL 证书您可以通过 PIP_OPTIONS 环境变量进行设置或者取消注释并编辑 PIP_OPTIONS 在 makefile 开头设置。
然后通过 doc 文件夹中的 make 命令完成实际编译。以下 make 命令可用
make html # generate HTML in html dir using Sphinx
make pdf # generate PDF as Manual.pdf using Sphinx and PDFLaTeX
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convertmake fasthtml # generate approximate HTML in fasthtml dir using Sphinx# some Sphinx extensions do not work correctly with thismake clean # remove intermediate RST files created by HTML build
make clean-all # remove entire build folder and any cached datamake anchor_check # check for duplicate anchor labels
make style_check # check for complete and consistent style lists
make package_check # check for complete and consistent package lists
make link_check # check for broken or outdated URLs
make spelling # spell-check the manual
3.8.2.使用 CMake 构建
还可以在 CMake 构建目录中创建手册的 HTML 版本并且仅 HTML 版本。使用此选项的原因是在通过 cmake --build . --target install CMake 构建后安装 LAMMPS 时将 HTML 手册页的安装包含到“安装”步骤中。文档构建包含在默认构建目标中但也可以通过 cmake --build . --target doc 独立请求。如果您需要将其他选项传递给 pip 命令才能工作例如使用 Web 代理或指向其他 SSL 证书您可以通过 PIP_OPTIONS 环境变量进行设置。
-D BUILD_DOCvalue # yes or no (default)
3.8.3. HTML 的先决条件
要运行 HTML 文档构建工具链必须在本地安装 python 3、git、doxygen 和 virtualenv。以下是常见设置的说明
Ubuntu
sudo apt-get install git doxygen
RHEL or CentOS (Version 7.x)sudo yum install git doxygen
Fedora or RHEL/CentOS (8.x or later)sudo dnf install git doxygen
MacOS如果您的 macOS 系统上没有 Python 3您可以从 https://www.python.org 下载最新的 Python 3 macOS 软件包并安装。这将安装 Python 3 和 pip3。
3.8.4. PDF 的先决条件
除了构建 HTML 格式手册所需的工具之外还需要支持 PDFLaTeX 的工作 LaTeX 安装以及精选的 LaTeX 样式/包。要运行 PDFLaTeX 翻译还需要安装 latexmk 脚本。
3.8.5. ePUB 和 MOBI 的先决条件
除了构建 HTML 格式手册所需的工具之外还需要使用一些附加 LaTeX 包以及 dvipng 工具来安装有效的 LaTeX以将嵌入式数学表达式透明地转换为嵌入式图像。
要将生成的 ePUB 文件转换为 MOBI 格式文件对于无法读取 ePUB 的电子书阅读器如 Kindle您还需要安装“calibre”软件中的 ebook-convert 工具。 https://calibre-ebook.com/ 输入 make mobi 将首先创建 ePUB 文件然后对其进行转换。特别是在 Kindle 阅读器上您还支持 PDF 文件因此您可以下载并查看 PDF 版本作为替代方案。
3.8.6. 开发者须知
当向 LAMMPS 代码添加新样式或选项时需要相应的文档并且需要更新 src 文件夹中的现有文件或添加新文件。这些文件以 reStructuredText 标记编写以便使用 Sphinx 工具进行翻译。
在提供任何文档之前请检查 HTML 和 PDF 格式文档是否可以正确翻译。在测试 html 翻译期间您可以使用 make fasthtml 命令进行近似翻译即并非所有 Sphinx 功能和扩展都可以工作但运行速度非常快因为它只会翻译自此以来已更改的文件最后一个 make fasthtml 命令。
另请检查控制台的输出是否有任何警告或问题。将自动运行多个测试
测试所有锚标签及其引用的正确性测试所有 LAMMPS 包 源位于 lammps/src 中的文件夹是否已记录并列出。典型的警告会显示包含可疑新包代码的文件夹名称以及需要列出它们的文档文件
Found 88 packages
Package NEWPACKAGE missing in Packages_list.rst
Package NEWPACKAGE missing in Packages_details.rst
仅使用标准的可打印 ASCII 文本字符的测试。这将运行命令 env LC_ALLC grep -n [^ -~] src/*.rst 从而打印所有有问题的行并在屏幕上添加文件名和行号。特殊字符例如希腊字母、上标或下标、数学表达式或埃符号( Å, :math:x^2 \mathrm{E}_{LJ} 、 :math:\frac{1}2}\mathrm{N} x\to\infty 或 :math:\AA 。嵌入式 LaTeX 通过 MathJax 在 HTML 输出中呈现并通过将嵌入文本传递给 LaTeX 在 PDF 输出中呈现。不过必须要小心因为在任一模式下使用宏和功能都存在限制因此建议始终检查任何新的或更改的文档是否能够正确地使用任一输出进行翻译和渲染。测试所有样式是否都已记录并在各自的概述页面中列出。带有警告的典型输出如下所示
Parsed style names w/o suffixes from C tree in ../src:Angle styles: 21 Atom styles: 24Body styles: 3 Bond styles: 17Command styles: 41 Compute styles: 143Dihedral styles: 16 Dump styles: 26Fix styles: 223 Improper styles: 13Integrate styles: 4 Kspace styles: 15Minimize styles: 9 Pair styles: 234Reader styles: 4 Region styles: 8
Compute style entry newcomp is missing or incomplete in Commands_compute.rst
Compute style entry newcomp is missing or incomplete in compute.rst
Fix style entry newfix is missing or incomplete in Commands_fix.rst
Fix style entry newfix is missing or incomplete in fix.rst
Pair style entry new is missing or incomplete in Commands_pair.rst
Pair style entry new is missing or incomplete in pair_style.rst
Found 6 issue(s) with style lists
此外还可以选择使用 make spelling 对整个手册运行拼写检查。这需要一个名为 enchant 的库。为了避免打印出误报例如关键字、名称、缩写可以将它们添加到文件 lammps/doc/utils/sphinx-config/false_positives.txt 中。
