Introduce phpdoc guides builder #594
Conversation
|
I started adding tasks for the things I want to do in this PR, will add more when I find issues. |
|
@SenseException could you please give me some direction on how to continue with this. I do see that tests are needed and some static analysis issues must be resolved. My first intention was to keep the old doc rendering working if needed I can restore that but I needed to remove some logic in the copy actions because I replaced the way the sidebar menu is moved. I'm sure this change will break the search as I didn't address that yet and we could also remove all old rst-parser related code to make this a fresh restart. But I'm not sure we should cover all that in this PR. Please let me know what you think. |
|
I've left some comments in the code rather doing a first review. Some (probably now outdated) tests are failing and the static analysis issues need to be addressed. |
|
Suggestion: target |
jaapio
force-pushed
the
phpdoc-guides
branch
2 times, most recently
from
3e4e636 to
9a1297d
Compare
I introduced an interface to be able to switch between the different implementations. The first setup of guides is done at the required locations and allows us to render the documentation. However this doesn't work yet without issues. More might be needed consider this work in progress.
jaapio
force-pushed
the
phpdoc-guides
branch
3 times, most recently
from
9b7c5c1 to
a350f85
Compare
jaapio
force-pushed
the
phpdoc-guides
branch
from
a350f85 to
08e4916
Compare
jaapio
force-pushed
the
phpdoc-guides
branch
from
61f4c38 to
0e6b6cd
Compare
|
Ok guys, this seems to be green and passing. I'm really looking forward to your experience and review. Let me know if there are any questions! |
|
Very few comments on my end, this looks good. What are the next steps? We merge this, then review the staging website, and work on fixing whatever is broken? |
There was a problem hiding this comment.
Very few comments on my end, this looks good. What are the next steps? We merge this, then review the staging website, and work on fixing whatever is broken?
stage isn't part of a process, but more a trigger and test-branch if you want to share changes that more people are supposed to look into. Since stage became a target branch for this PR, after all comments were addressed, it would be merged to stage and we would test the documentation and "fix whatever is broken" as you already mentioned it.
AFAIK is the search indexer the only thing we currently cannot test on stage.
| @@ -0,0 +1,29 @@ | |||
| --- | |||
| title: "{{ node.pageTitle | yaml_encode }}" | |||
There was a problem hiding this comment.
What's the purpose of this yaml encoding?
| title: "{{ node.pageTitle | yaml_encode }}" | ||
| docsIndex: {% if node.filePath ends with 'index' %}true{% else %}false{% endif %} | ||
|
|
||
| docsSourcePath: "/en/{{ node.filePath }}.rst" |
There was a problem hiding this comment.
Needs to be tested for old Doctrine 1 once we have this in the stage branch.
| {% endif %} | ||
| {%~ endfor -%} | ||
|
|
||
| {{ "{% endverbatim %}" }} |
There was a problem hiding this comment.
What is this output for?
|
To answer some of the questions asked in general. We need to have a look at the result of the docs parser, which are twig templates. That's why you see yaml and twig tags in the output and templates. Those templates are picked up by the website build command and processed into the actual page. This wasn't my idea but how it currently works. Given the fact that the docs templates do not have information about the other projects and pages I do understand this approach. But it results into very interesting template code. |
As toctree does modify the structure of the docs, which results in infinitif loops when items refer to eachother, we switched to menu.
To allow full usage of the configuration move the theme configuration to a compiler pass that will set the value.
|
Thanks for your reviews! |
I introduced an interface to be able to switch between the different implementations. The first setup of guides is done at the required locations and allows us to render the documentation. However this doesn't work yet without issues. More might be needed consider this work in progress.