-
-
Notifications
You must be signed in to change notification settings - Fork 504
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
doc: Validate documentation rst with phpdocumentor #2646
Conversation
8cd3137
to
b9194da
Compare
@@ -1,7 +1,7 @@ | |||
Implementing ArrayAccess for Domain Objects | |||
=========================================== | |||
|
|||
.. sectionauthor:: Roman Borschel ([email protected]) | |||
.. sectionauthor:: Roman Borschel <[email protected]> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WARNING: Content of
.. sectionauthor:: name <email>
must specify a name and can also specify an email
docs/en/sidebar.rst
Outdated
@@ -1,3 +1,4 @@ | |||
:orphan: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WARNING: Document "sidebar" isn't included in any toctree. Include it in a
.. toctree::
directive or add:orphan:
in the first line of the rst document {"rst-file":"sidebar.rst"} []
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I noted that the ORM's documentation workflow manually added :orphan:
before validating. Is there a particular reason that approach was preferred there instead of modifying the RST directly as you've done here?
I don't have any objections to this, but I wonder if it'd be worth suggesting upstream to the ORM team.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
orphan
is not supported by doctrine/rst-parser
, which we still use for generating our docs
This means that if you don't use the trick I used, you are going to end up with :orphan:
being printed above the sidebar of your docs 😅
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the clarification, I've adopted your solution that adds :orphan:
in the job.
.. |FQCN| raw:: html | ||
<abbr title="Fully-Qualified Class Name">FQCN</abbr> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WARNING: No replacement was found for variable |FQCN| {"rst-file":"reference/custom-mapping-types.rst"}
docs/en/sidebar.rst
Outdated
@@ -1,3 +1,4 @@ | |||
:orphan: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I noted that the ORM's documentation workflow manually added :orphan:
before validating. Is there a particular reason that approach was preferred there instead of modifying the RST directly as you've done here?
I don't have any objections to this, but I wonder if it'd be worth suggesting upstream to the ORM team.
@@ -0,0 +1,39 @@ | |||
name: "Documentation" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Noted that this was adapated from the ORM action.
5c02bb2
to
e14dd0a
Compare
Summary
Use phpdocumentator cli to validate rst files.