Giới hạn đánh dấu Sphinx LaTeX

Question

Tôi đang cố gắng thực hiện ba điều cơ bản thực sự bên trong một chế độ toán học đa dòng trong Sphinx (phiên bản 1.1.2-1).

1. Viết gạch dưới như một phần của tên biến của tôi ngay cả trong chế độ toán học;
2. Sử dụng \big, \biggl, v.v., dấu phân tách để tạo dấu ngoặc đơn lớn và dấu ngoặc đơn;
3. và bao gồm văn bản thông thường như là một phần của phương trình.

Lưu ý hai điều sau đây. (1) Tôi đang sử dụng một chuỗi thô trong mã Python của tôi cho tài liệu đánh dấu Sphinx, vì vậy các dấu gạch chéo ngược không cần thiết cho ký tự thoát, và (2) Tôi không thực hiện chế độ toán học nội tuyến, được phân tách như thế này trong Sphinx:

:math:`Some math stuff goes here` regular text could go here... 

Thay vào đó, tôi đang làm nhiều dòng thứ, thường thích eqnarray trong LaTeX:

.. math:: 
    DividendYield &=& \frac{DVT(t)}{CurrentMarketCap} \\ 
    Avg_Assets &=& \biggl(A/B \biggr) \textrm { when B is not zero...} 

Hiện nay, tôi nhận được lỗi Sphinx (và các trang doc tạo ra trông giống như vô nghia), mà nói những điều như:

Unknown LaTeX command: textrm 

Điều tương tự cũng xảy ra với \biggl. Đối với dấu gạch dưới, nó chỉ luôn luôn diễn giải nó như thể tôi đang biểu thị một chỉ số, nhưng nếu tôi sử dụng \textunderscore hoặc các thủ thuật khác thì nó sẽ ném cùng một loại lỗi như trên.

Dấu gạch dưới trong chế độ toán học, lệnh textrm và dấu phân cách lớn là các phần cực kỳ cơ bản của mỗi gói TeX gốc mà tôi từng sử dụng. Vậy tại sao họ không thể tiếp cận được qua Sphinx?

Cập nhật

Một tập tin Python đặc biệt mà tôi đang làm việc trên tính toán dữ liệu Sổ Equity đối với tôi. Vì vậy, dưới đây, khi bạn nhìn thấy những thứ về BookEquity, đó là tài liệu tham khảo. Tôi không thể chạy quá trình xây dựng tài liệu của chúng tôi ngoại trừ thông qua một hệ thống kiểm soát phiên bản, do đó, làm cho một lỗi tái sản xuất là dễ nhất nếu tôi chỉ sửa đổi một tập tin hiện có.

Tuy nhiên, tất cả những gì tôi đã làm là thêm hàm lớp sau vào mã của mình, với một chuỗi tài liệu đơn giản.

def foo(self): 
    r""" 
    Sample docstring 

    .. math:: 
     Ax &=& b \\ 
     Cx &=& \biggl(\frac{x/y}\biggr) \textrm{ if y is not zero.} 
    """ 
    pass 

Và sau đó hình ảnh bên dưới là đầu ra đến từ việc tạo tài liệu với Nhân sư 1.1.2-1.

Nếu bạn nhấp chuột phải và chọn 'hình ảnh xem' bạn có thể nhìn thấy một phiên bản tốt hơn.

Answer 1

Bạn phải chỉnh sửa tệp cấu hình chuẩn mà sphinx-quickstart tạo, nếu không thì nhân sư sẽ bị chặn tại các khối toán học.Trong tập tin conf.py, tôi đã thay đổi

extensions = [] 

để

extensions = ['sphinx.ext.pngmath'] 

Sau đó các tập tin đầu tiên sau hơn hoặc ít làm việc;

.. foo documentation master file, created by 
    sphinx-quickstart on Thu Oct 25 11:04:31 2012. 
    You can adapt this file completely to your liking, but it should at least 
    contain the root `toctree` directive. 

Welcome to foo's documentation! 
=============================== 

Contents: 

.. toctree:: 
    :maxdepth: 2 

This is the first chapter 
========================= 

Instead, I am doing multi-line stuff, often like eqnarray in LaTeX: 

.. math:: 
    DividendYield &=& \frac{DVT(t)}{CurrentMarketCap} \\ 
    Avg_Assets &=& \biggl(A/B \biggr) \textrm { when B is not zero...} 

Nó đã tạo ra mã LaTeX sau cho mảnh toán:

\chapter{This is the first chapter} 
\label{index:welcome-to-foo-s-documentation}\label{index:this-is-the-first-chapter} 
Instead, I am doing multi-line stuff, often like eqnarray in LaTeX: 
\begin{gather} 
\begin{split}DividendYield &=& \frac{DVT(t)}{CurrentMarketCap} \\ 
Avg_Assets &=& \biggl(A/B \biggr) \textrm { when B is not zero...}\end{split}\notag\\\begin{split}\end{split}\notag 
\end{gather} 

Sự lựa chọn của việc sử dụng sự kết hợp của phân chia và thu thập có vẻ hơi lạ với tôi, và rõ ràng là không làm việc tốt với mã bạn đã viết cho eqnarray, nhưng điều này được mã hóa cứng trong Nhân sư.

Chạy pdflatex đã dừng tại \end{gather}, với lỗi Extra alignment tab has been changed to \cr. nhưng tôi đã có thể tiến hành quá trình đó bằng cách nhập nonstopmode. Đây cho tôi kết quả sau đây:

Trong khi vẫn có cái gì đó sai trái với sự liên kết (vì sự khác biệt giữa split và eqnarray môi trường), các textrm và biggl dường như làm việc tốt. (Lưu ý rằng bạn sẽ vẫn phải thoát dấu gạch dưới trong Average_Assets, nhưng đó là ngang bằng với khóa học, AFAICT).

Bạn có thể lấy đi bằng cách xử lý mã LaTeX được tạo, ví dụ: bằng cách thay thế \begin{gather}\begin{split} và \end{split}\notag\\\begin{split}\end{split}\notag\end{gather} bằng môi trường toán học mà bạn chọn.

Cập nhật:

Ảnh chụp màn hình từ bản cập nhật có vẻ là từ một trang web, không phải là một tài liệu LaTeX! Vì vậy, có vẻ với tôi rằng những gì đang tạo ra lỗi là trình xử lý chuyển đổi ký hiệu toán LaTeX thành một thứ mà trình duyệt có thể hiển thị. Điều đó có thể là MathJax hoặc jsMath. Từ khi xem mã, pngmath sẽ tạo ra các thông báo lỗi khác. Theo số this page, đoạn mã của bạn nên hoạt động trong mathjax. Từ jsMath symbols page, nó không giống như hỗ trợ jsmath \Biggl. Vì vậy, tôi đoán tốt nhất là Sphinx được cấu hình để sử dụng jsMath. Một cái nhìn tại nguồn của trang web được tạo ra sẽ cho bạn biết những gì được sử dụng để hiển thị toán học. Nếu dự đoán của tôi là chính xác, việc chuyển cấu hình để sử dụng mathjax và hơi thích ứng với phương trình của bạn có thể khắc phục được sự cố.

Update2: Tôi chắc chắn có thể xác nhận rằng nó hoạt động tốt với MathJax (xem bên dưới). Tuy nhiên, tôi chưa cài đặt jsMath.

Answer 2

Cập nhật

Như đã đề cập, nhân sư sử dụng gather và split cho chế độ toán học. Theo phân chia AMS math guide, cần có một dấu hiệu $.Vì vậy,

.. math:: 
    DividendYield &= \frac{DVT(t)}{CurrentMarketCap} \\ 
    Avg_Assets &= \biggl(A/B \biggr) \textrm { when B is not zero...} \\ 
    Avg \_ Assets &= \biggl(\frac{A}{B}\biggr) \textrm{ when B is not zero...} 

.. autofunction:: mymodule.foo 

với foo định nghĩa là

def foo(self): 
    r"""Sample docstring 

    .. math:: 
     Ax &= b \\ 
     Cx &= \biggl(\frac{x}{y} \biggr) \textrm{ if y is not zero.} 
    """ 
    pass 

ám tốt với latexpdf và html với MathJax extension.

Lưu ý rằng tôi đã sử dụng \_ cho gạch trong chế độ toán học, mà làm việc, nhưng \textunderscore đã không làm việc (Bạn phải tải gói bổ sung Tôi nghĩ, xem this question trên tex.stackexchange.com). Vì vậy, khi nó đi ra, tôi nghĩ câu hỏi của bạn rõ ràng là một câu hỏi Tex.

Tôi không xóa câu trả lời trước đó của mình, tuy nhiên nó chỉ áp dụng cho trình tạo mủ cao su, không áp dụng cho trình tạo html.

Original câu trả lời

Sphinx tạo "bất thường" mã latex. Nó sử dụng gather và split cho các phương trình (có xem xét nguồn mủ cao su mà nó tạo ra).

Vấn đề là, không có cách nào đơn giản để sửa đổi nguồn latex mà nó tạo ra. Bạn phải xử lý nguồn mủ cao su để lấy mã latex cao cấp "khoa học".

Nhân sư được thiết kế cho tài liệu html (và bởi nhà phát triển web tôi nghĩ), các vấn đề về latex (và khoa học "như số, bảng và phương trình được đánh số) dường như không phải là trọng tâm chính của dự án. Nhân tiện, mã của bạn hiển thị tốt với html với phần mở rộng mathjax.

Tôi nghĩ rằng tôi còn nhớ một số lời chỉ trích của các nhà phát triển docutils về chủ đề này: docutils có một nhà xây dựng latex (có vẻ là "tốt hơn"), nhưng người xây dựng này không được sử dụng bởi nhân sư.

Đã từng có thông báo về dự án được gọi là relatex (link) trong danh sách gửi thư để xử lý mã latex được tạo bởi nhân sư. Nhưng tôi không chắc chắn về tình trạng phát triển. Tôi sử dụng mã của riêng mình, mà tôi đã có sẵn here (tiếc là nó là một hỗn hợp của tiếng Đức một tiếng Anh). Tôi không nghĩ rằng nó rất hữu ích, bởi vì tôi quyết định rằng nó là phức tạp để sau quá trình latex nhân tạo và tôi chuyển sang mủ nguyên chất. Vì vậy, tôi không phát triển thêm nữa. Tuy nhiên các bước cơ bản là

• tạo phong cách mủ của riêng bạn và mẫu
• hãy Sphinx tạo ra nó là mã latex
• sau quá trình mã latex và dán nó vào mẫu
• của bạn sử dụng một hệ thống xây dựng cho LaTeX để tạo bản pdf từ mã của bạn

Tôi đã thích nghi với nhân sư Makefile để làm điều này trong một bước. Là hệ thống xây dựng tôi đã sử dụng rubber (hiện tại tôi sẽ sử dụng latexmk).

Answer 3

Bây giờ (2016) Sphinx chỉ thị toán học có tùy chọn :nowrap: trở toàn quyền kiểm soát cho người sử dụng, làm như vậy chỉ

.. math:: 
    :nowrap: 

    \begin{eqnarray} 
     y & = & ax^2 + bx + c \\ 
     f(x) & = & x^2 + 2xy + y^2 
    \end{eqnarray} 

ám tốt trong cả hai html và latexpdf.