Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Remove module list in the sidebar #444

Draft
wants to merge 8 commits into
base: main
Choose a base branch
from
Draft

WIP: Remove module list in the sidebar #444

wants to merge 8 commits into from

Conversation

core-man
Copy link
Member

@core-man core-man commented Jun 21, 2021

Fixes #443.

@core-man core-man requested a review from seisman June 21, 2021 03:54
@seisman
Copy link
Member

seisman commented Jun 21, 2021

这会导致一堆警告,因为这些文件都没有被包含到文档里。

@github-actions
Copy link
Contributor

github-actions bot commented Jun 21, 2021

This comment was written by the Continuous Documentation bot!

@core-man
Copy link
Member Author

core-man commented Jun 21, 2021

See sphinx-doc/sphinx#5281. We could try two solutions based on https://stackoverflow.com/questions/15249340/warning-document-isnt-included-in-any-toctree-for-included-file.

  1. Add :orphan: to the top of the `.rst* document to get rid of the warning. See file-wide-metadata
  2. Update conf.py file with something like: exclude_patterns = ['modules/*.rst']. But this will also exclude index.rst. See exclude_patterns

@seisman
Copy link
Member

seisman commented Jun 21, 2021

See sphinx-doc/sphinx#5281. We could try two solutions based on stackoverflow.com/questions/15249340/warning-document-isnt-included-in-any-toctree-for-included-file.

  1. Add :orphan: to the top of the `.rst* document to get rid of the warning
  2. Update conf.py file with something like: exclude_patterns = ['modules/*.rst']. But this will also exclude index.rst.

由于没有被加到 toctree 里,所有模块的文档都会变成“野”文件。在显示上会有不同:

Before After
image image

基于同样的原因,我猜测所有模块都不会被显示到PDF里。

Comment on lines -77 to +78
api/index
module/index
api/index
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #442 (comment):

api也可以放在模块后面,一来我们很少看api 二来英文放在后面显得和谐

@core-man
Copy link
Member Author

core-man commented Jun 21, 2021

由于没有被加到 toctree 里,所有模块的文档都会变成“野”文件。在显示上会有不同:

Before After
image image
基于同样的原因,我猜测所有模块都不会被显示到PDF里。

我在 e83c630 中将 :orphan: 加入 basemap 测试,因为我本地机器无法编译。

@core-man
Copy link
Member Author

还是表现为“野”文档,虽然网址没问题,警告也消失了。PDF 估计也有问题。

还是需要把所有文档包含在 TOC 里,所以按照类型包含每个模块以减少 TOC 的长度?

@core-man
Copy link
Member Author

core-man commented Jun 25, 2021

I reverted the changes. How about generating some .rst files to include different kinds of modules, e.g., session, plotting, 1d-data? For example, the session.rst will contain begin, end, figure, subplot, inset, docs, and clear. This will make the url for each module look like https://docs.gmt-china.org/latest/module/session/end/ instead of https://docs.gmt-china.org/latest/module/end/.

@seisman
Copy link
Member

seisman commented Jun 25, 2021

I reverted the changes. How about generating some .rst files to include different kinds of modules, e.g., session, plotting, 1d-data? For example, the session.rst will contain begin, end, figure, subplot, inset, docs, and clear. This will make the url for each module look like docs.gmt-china.org/latest/module/session/end instead of docs.gmt-china.org/latest/module/end.

No, do not break the URLs.

source/module/index.rst Outdated Show resolved Hide resolved
@core-man core-man marked this pull request as draft June 30, 2021 07:03
@core-man core-man changed the title Remove module list in the sidebar WIP: Remove module list in the sidebar Jul 1, 2021
@core-man core-man changed the title WIP: Remove module list in the sidebar Remove module list in the sidebar Jul 7, 2021
@core-man core-man marked this pull request as ready for review July 7, 2021 12:17
@@ -84,6 +84,7 @@
html_theme_options = {
"prev_next_buttons_location": "bottom",
"sticky_navigation": False,
"includehidden": False,
Copy link
Member Author

@core-man core-man Jul 7, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

加这个设置的话,所有使用 :hidden: 的文件都不会显示在左侧了,但是目前以下文件使用了 :hidden::

  • index.rst: 这个文档都没有目录了 😄
  • dataset/index.rst
  • migrating/index.rst
  • module/index.rst
  • option/index.rst
  • proj/index.rst

为了左侧目录也能显示,就要在这些文件里去掉 hidden,但这样的话,页面里就会有目录。

看来必须二选一了。

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个问题仍没有办法解决吗?
gmt 官方也是用的 "includehidden": False,或许我们应该和官方一致,减少维护负担

@core-man core-man removed the module label Jul 9, 2021
@core-man core-man changed the title Remove module list in the sidebar WIP: Remove module list in the sidebar Jul 16, 2021
@core-man core-man marked this pull request as draft July 16, 2021 20:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

目录中按类别排序模块?
3 participants