-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
Added standard bundle installation instructions #4163
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
Changes from 7 commits
b297d29
11db860
21ce2c0
ed96447
c39f7d3
322ec60
4b29de2
41ce2a5
7a6644b
35dddba
7097070
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -194,6 +194,60 @@ Extensive documentation should also be provided in the | |
the ``Resources/doc/`` directory; the ``Resources/doc/index.rst`` file is | ||
the only mandatory file and must be the entry point for the documentation. | ||
|
||
Installation Instructions | ||
~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
In order to ease the installation process of third-party bundles, consider using | ||
the following standardized instructions in your ``README.md`` file. | ||
|
||
.. sidebar:: Installation Instructions Template | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I find this sidebar really strange There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agree! It's strange form the point of view of documentation source ... but I think it looks OK from the point of view of the documentation reader: see a screenshot of the result If you still think that this is wrong, I'll change it. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah, I think it's wrong. A sidebar shows something that is not the main content, but just a little "side information". Things that are good to know, etc. (the "How is this event used in the Symfony Framework" sidebars of the HttpKernel docs are a good example of this). In this case, it is the most important information of the complete section. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The sidebar is now gone. |
||
|
||
This template assumes that your bundle is in its ``1.x`` version. If not, | ||
change the ``"~1"`` installation version accordingly (e.g. ``"~2"``). | ||
|
||
.. code-block:: text | ||
|
||
Installation | ||
============ | ||
|
||
Step 1: Download the Bundle | ||
--------------------------- | ||
|
||
Use Composer to add the bundle as a new dependency of your project: | ||
|
||
``` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
seems to be more reasonable. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. that's github specific markup, let's keep using standard markdown There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks, I thought it was part of the markdown specifications. But in this case we should keep the example as it is. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @wouterj it's true that this started as GitHub-specific but it's generally accepted now. In addition, 99.99% of the bundles are published on GitHub. And another compelling reason: if you are able to develop a Symfony bundle, you definitely know how to manage all these Markdown formatting issues. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thus, having syntax highlighting in the code snippets of the readme is much better. So I'm +1 for keeping them (the reason to use Markdown as format is related to Github anyway) |
||
$ composer require <package-name> "~1" | ||
``` | ||
|
||
This command requires to have Composer installed globally, as explained | ||
in the [installation chapter](https://getcomposer.org/doc/00-intro.md) | ||
of Composer documentation. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. wouldn't be "have Composer installed globally"? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. And we could also use "to have Composer globally installed". I'm not sure what to do. We need the help of some native speaker. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I agree with @raulfraile. I would also remove everything after the comma and directly link "Composer globally installed". |
||
|
||
Step 2: Enable the Bundle | ||
------------------------- | ||
|
||
Then, enable the bundle adding the following line in the `AppKernel` | ||
class of your project: | ||
|
||
```php | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. same here |
||
<?php | ||
// app/AppKernel.php | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We can add a |
||
// ... | ||
|
||
public function registerBundles() | ||
{ | ||
$bundles = array( | ||
// ... | ||
new <vendor>\<bundle-name>\<bundle-long-name>(), | ||
); | ||
} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I usually add a There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If we add the return statements, I don't think that this is necessary. Usually you would simply add the new bundle at the end of the array and then return the |
||
``` | ||
|
||
Optionally, you can add *Step 3*, *Step 4*, etc. to explain other required | ||
installation steps, such as registering routes or dumping assets. | ||
|
||
|
||
Routing | ||
------- | ||
|
||
|
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.
you should either add a note saying this is a rST template, or give also a Markdown template. Most projects are using Markdown for the readme on github.
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.
You are right. RST is the official format for the bundle documentation, but 99% of bundles hosted on GitHub use
README.md
instead ofREADME.rst
. I've switched the template to Markdown.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.
well, the best practice in the doc was written at a time where symfony.com was expected to have a repository of bundles with their doc being rendered (KnpBundles appeared as a third-party solution to this problem because the official tool announced by Fabien was not yet there, and never became a reality given we then choose composer meaning that KnpBundles and Packagist can probably be enough and people can use libraries which are not bundles). The de-facto standard then became Markdown because everyone is using Github (well, mostly at least) and it used to suck at rendering rST (3 years ago when building the Symfony2 ecosystem, the
code-block
directive was not supported by their rST renderer for instance) while Markdown was well renderedThere 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.
To make myself more clear, this is what I would like to have:
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.
but
..raw
does not achieve this. It let you pass unprocessed context (i.e. eitherhtml
orlatex
or other format, which is why it asks you for a format btw: you have to provide it for each output format).What you expect in your image is still a
<pre>
tag in HTML, and it is technically a code-block (so<pre><code>
is more semantic).the only difference with the rendering of
..code-block
is that you don't want line numbers (this is fine, Sphinx has an option to omit them in its directive) and a different background color (and this is a matter of theming) But I could totally live with the code being on a block background, and people will be able to copy-paste it.See http://symfony.com/doc/current/contributing/code/patches.html#make-a-pull-request and you will see that the code snippet containing the pull-request template can totally be copy-pasted (we did not even bothered about removing line numbers on it)
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.
You are right! We just need a simple
.. code-block:: text
directive to output the Markdown content "as is".