Comments (3)
Exercise I
Just using vanilla .. include::
directives to re-bundle pages does not work well.
Warning, treated as error:
../docs/appendices/release-notes/5.0.0.rst:139:Duplicate target name, cannot be used as a unique reference: "breaking changes".
from crate-docs-theme.
Exercise II
Thoughts
At sphinx-doc/sphinx#10744 (comment), we discovered that the MyST include directive offers a heading-offset
directive option, which can
offset all the heading levels [of the included page] by a positive integer number.
-- executablebooks/MyST-Parser#262 (comment)
Based on that, @felixvd suggested at sphinx-doc/sphinx#10744 (comment) to place each include under its own header, and using the heading-offset
directive option as intended.
Attempt 1
In 5.x.x.rst
, we said:
#############
Release 5.0.0
#############
.. include:: 5.0.0.rst
However, it does not work, because the included page includes reference anchors, and parsing them twice makes Sphinx croak.
Warning, treated as error:
/Users/amo/dev/crate/sources/crate/docs/appendices/release-notes/5.0.0.rst:5:duplicate label version_5.0.0, other instance in /Users/amo/dev/crate/sources/crate/docs/appendices/release-notes/5.0.0.rst
Attempt 2
Then, we tried to use MyST, as @felixvd suggested. In 5.x.x.md
, we said:
# Release 5.0.0
```{include} 5.0.0.rst
:heading-offset: 1
```
Unfortunately, files written in MyST Markdown are apparently not able to include reStructuredText files properly, so the result looks like that. Maybe there are corresponding options to make this detail work, maybe not.
from crate-docs-theme.
Attempt 3
Idea
Using the :start-line:
option of the .. include::
directive could be a potential quick solution/workaround, in order to skip the reference and heading at the top of the included page.
.. include:: member.rst
:start-line: 5
-- https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment
Outcome
It does not work well, because within each page, just using
See `Breaking Changes`_.
is actually the culprit here, which causes this warning.
Warning, treated as error:
../docs/appendices/release-notes/5.0.0.rst:136:Duplicate target name, cannot be used as a unique reference: "breaking changes".
from crate-docs-theme.
Related Issues (20)
- Improve rendering of sphinx-togglebutton
- "Edit page" does not work on repositories using the "main" branch HOT 1
- Menu items got lost HOT 1
- Fix package metadata
- Hide new feedbackbox on the search page HOT 1
- Page tools rendering glitch on CrateDB Reference, version 3.3
- Search: Set focus to the query field
- Using `sphinxext-photofinish` for creating responsive images HOT 1
- Use MyST-NB for Jupyter Notebook Publishing
- SQL-99 RTD URL errors HOT 2
- New <h1> headline font: Montserrat HOT 8
- Documentation feedback on /docs/links.md HOT 2
- Move search button to the top right corner HOT 1
- Missing `index.html` within link generated to designate the canonical URL HOT 2
- CrateDB Guide Configuration: Do not set `language = ""` HOT 1
- Documentation feedback: Links to pages are broken after refactoring HOT 2
- Documentation: Set up comprehensive G4A view HOT 3
- Jira Document - environment of our docs HOT 5
- Version toggler and feedback dropdown look odd HOT 16
- Highlighting of "current" item in primary navigation is wrong HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from crate-docs-theme.