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.getpreferredencoding(False).
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()
Returns underlying file descriptor if one exists.
OSError is raised 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 n characters from stream.
Read from underlying buffer until we have n characters or we hit EOF. If n 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.
Returns an empty string if EOF is hit immediately.
- 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, /)
Change stream position.
Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are:
0 – start of stream (the default); offset should be zero or positive
1 – current stream position; offset may be negative
2 – end of stream; offset is usually negative
Return the new absolute position.
- 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 current 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(). Returns the new size.
- writable()
Return whether object was opened for writing.
If False, write() will raise OSError.
- write(text, /)
Write string to stream. Returns 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