sphinx
参与贡献
调试技巧
https://www.sphinx-doc.org/en/master/internals/contributing.html#debugging-tips
html主题
https://www.sphinx-doc.org/en/master/usage/theming.html
心水主题: sphinx-rtd-theme
核心配置
html_theme
html_theme_options
sphinx-rtd-theme源码分析
小技巧
了解主题源码有利于参与主题的开源贡献
技术栈分析
使用Sass编写的css样式
使用webpack作为前端开发和构建工具
核心文件
theme.conf ; 主题配置文件, 新版sphinx推荐使用 ``.toml`` 格式: https://www.sphinx-doc.org/en/master/development/html_themes/index.html#theme-configuration-theme-toml
static ; 静态资源文件, 包括css, js, img等
*.html ; 主题模板文件, 名称是约定号的
事件机制
https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html
应用场景: autodoc插件用 autodoc-skip-member 事件忽略指定的方法
conf.py .. code-block:: python
- def autodoc_skip_member(app, what, name, obj, skip, options):
- if name == “write”:
# 不生成write方法的文档 return True
- def setup(app):
# 注册回调方法 app.connect(‘autodoc-skip-member’, autodoc_skip_member)
index.rst .. code-block:: rst
- class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)
Character and line based layer over a BufferedIOBase object, buffer.
encoding gives the name of the encoding that the stream will be decoded or encoded with. It defaults to locale.getencoding().
errors determines the strictness of encoding and decoding (see help(codecs.Codec) or the documentation for codecs.register) and defaults to “strict”.
newline controls how line endings are handled. It can be None, ‘’, ‘n’, ‘r’, and ‘rn’. It works as follows:
On input, if newline is None, universal newlines mode is enabled. Lines in the input can end in ‘n’, ‘r’, or ‘rn’, and these are translated into ‘n’ before being returned to the caller. If it is ‘’, universal newline mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.
On output, if newline is None, any ‘n’ characters written are translated to the system default line separator, os.linesep. If newline is ‘’ or ‘n’, no translation takes place. If newline is any of the other legal values, any ‘n’ characters written are translated to the given string.
If line_buffering is True, a call to flush is implied when a call to write contains a newline character.
- close()
Flush and close the IO object.
This method has no effect if the file is already closed.
- detach()
Separate the underlying buffer from the TextIOBase and return it.
After the underlying buffer has been detached, the TextIO is in an unusable state.
- encoding
- errors
- fileno()
Return underlying file descriptor if one exists.
Raise OSError if the IO object does not use a file descriptor.
- flush()
Flush write buffers, if applicable.
This is not implemented for read-only and non-blocking streams.
- isatty()
Return whether this is an ‘interactive’ stream.
Return False if it can’t be determined.
- newlines
- read(size=-1, /)
Read at most size characters from stream.
Read from underlying buffer until we have size characters or we hit EOF. If size is negative or omitted, read until EOF.
- readable()
Return whether object was opened for reading.
If False, read() will raise OSError.
- readline(size=-1, /)
Read until newline or EOF.
Return an empty string if EOF is hit immediately. If size is specified, at most size characters will be read.
- reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)
Reconfigure the text stream with new parameters.
This also does an implicit stream flush.
- seek(cookie, whence=0, /)
Set the stream position, and return the new stream position.
- cookie
Zero or an opaque number returned by tell().
- whence
The relative position to seek from.
Four operations are supported, given by the following argument combinations:
seek(0, SEEK_SET): Rewind to the start of the stream.
seek(cookie, SEEK_SET): Restore a previous position; ‘cookie’ must be a number returned by tell().
seek(0, SEEK_END): Fast-forward to the end of the stream.
seek(0, SEEK_CUR): Leave the current stream position unchanged.
Any other argument combinations are invalid, and may raise exceptions.
- seekable()
Return whether object supports random access.
If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().
- tell()
Return the stream position as an opaque number.
The return value of tell() can be given as input to seek(), to restore a previous stream position.
- truncate(pos=None, /)
Truncate file to size bytes.
File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Return the new size.
- writable()
Return whether object was opened for writing.
If False, write() will raise OSError.
- write(text, /)
Write string s to stream.
Return the number of characters written (which is always equal to the length of the string).
参见
相关issue(open状态): https://github.com/sphinx-doc/sphinx/issues/12674