laminas/laminas-coding-standard

Updates for documentation needed

Closed this issue · 11 comments

froschdesign commented

Bug Report

  • wrong installation command
  • wrong site description
  • the page "Coding Style Guide" is too long
  • wrong indentation in lists for code examples
  • wrong formatting in blockquotes
  • wrong or no syntax for links
  • unneeded PHP tags
  • unneeded numbering in headlines
  • invalid the very first code example in v2 docs
  • …
geerteltink commented

the page "Coding Style Guide" is too long
unneeded numbering in headlines

The coding style follows the same format as PHP-fig PSR-12 as it is our extension to it. If you need to split it, at least keep the numbering so we can easily find it and keep the same structure. The ruleset itself is linked to the same numbering. If sniffs change we know where to find them and where to adjust the docs.

  • 👍1
froschdesign commented

It would be good to replace to "autogenerated" homepage which can be done with a separate configuration in mkdocs.yml.
This allows to add the correct installation command for Composer.

Example: https://github.com/laminas/tutorials/blob/bcdd0867ce63774b04605e302ef7416fa657473d/mkdocs.yml#L42-L43

froschdesign commented

The ruleset itself is linked to the same numbering.

Very good point and therefore we should leave the numbering as is.

  • 👍1
geerteltink commented

It would be good to replace to "autogenerated" homepage which can be done with a separate configuration in mkdocs.yml.
This allows to add the correct installation command for Composer.

Example:

Which file is then used as the homepage? You have a template I can use?
Can't we add some kind of flag that displays the --dev composer requirement? This isn't the only component that should be installed this way.

froschdesign commented

@geerteltink

Which file is then used as the homepage?

Use the existing index.md file.
There you can add all content without restrictions like in any other page. Only the site name and description is added at the beginning. (See: https://github.com/laminas/documentation-theme/blob/master/theme/pages/homepage.html)

Can't we add some kind of flag that displays the --dev composer requirement?

Unfortunately no.

geerteltink commented

I meant something like this:

{% if config.extra.show_special_homepage %}
    {{ page.content }}

    {% if config.extra.component_list %}
        {% include "partials/component-list.html" %}
    {% endif %}
{% else %}
    <h2>Installation</h2>
    <h3>Using Composer</h3>
    <pre><code class="language-bash">$ composer require {% if config.extra.require_dev %}--dev {% endif %}{{ config.extra.repo_name }}</code></pre>
{% endif %}

Why create a custom page just to add 1 word, which needs to be updated manually if you decide to change the main template.
I can create a PR if you want. What you prefer: config.extra.require_dev or config.extra.dev_tool.

froschdesign commented

Why create a custom page just to add 1 word, which needs to be updated manually if you decide to change the main template.

The problem is another one: duplication. See:

Beside that the description is different and the reader is irritated that the description occurs twice at different places, this always leads to errors, as only one side is changed during an update.

A current example can be found here in this repository:

A quick solution:

  • copy the content from the file v2/intro.md into index.md
  • remove the introduction page from the navigation configuration
  • add show_special_homepage : true to the extra section in the configuration

This replaces the "autogenerated" homepage with introduction and the description for installation includes needed steps.

froschdesign commented

I can create a PR if you want. What you prefer: config.extra.require_dev or config.extra.dev_tool.

It would be great if you can bring your idea into the related issue report: laminas/documentation#12

Thanks in advance!

froschdesign commented

@geerteltink
--dev is now here! (see #31) 😃

  • 🎉1
geerteltink commented

@froschdesign Do we still need something here or can this be closed?

froschdesign commented

@geerteltink
All done! 👍

  • 👍1