add mention of symfony.com re folder structure

symfony · darrylhein · Nov 5, 2016 · Nov 8, 2016 · Nov 8, 2016 · Nov 16, 2016
commit 99dc9a96cb96c7e264d951ddcb103694ef80ba9b
diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst
@@ -185,7 +185,8 @@ Documentation
 All classes and functions must come with full PHPDoc.

 Extensive documentation should also be provided in the ``Resources/doc/`` 
-directory. The index file (for example ``Resources/doc/index.rst`` or 
+directory (though only required when the documentation is shown on symfony.com).
+The index file (for example ``Resources/doc/index.rst`` or 
 ``Resources/doc/index.md``) is the only mandatory file and must be the entry 
 point for the documentation. The 
 :doc:`reStructuredText (rST) </contributing/documentation/format>` is the most
-Original file line number
+Diff line change
@@ -185,7 +185,8 @@ Documentation
     All classes and functions must come with full PHPDoc.
     Extensive documentation should also be provided in the ``Resources/doc/``
-    directory. The index file (for example ``Resources/doc/index.rst`` or
+    directory (though only required when the documentation is shown on symfony.com).
             Copy link

  
      
    
  

  
      

  
  Member


      

  

  
    
      

      
            stof
  

      

      

      


        Nov 16, 2016


      
    

  


        
      
  
  
  
    

    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.
    

    
      
      


  


  
    
      the sentence in braces looks wrong to me. Providing doc is required when sharing your bundle. the sentence looks like doc is required only when showing it on symfony.com
Putting it inside Resources/doc/ and using rST is what is required when rendering it on symfony.com.

when rendering the doc elsewhere, we could live with the doc being elsewhere (in a docs folder at the root of the repo for instance, which is a convention supported by github pages now) and in any format (as long as you provide a version readable by humans somewhere, and link to it)
    
  
  


    

        
      
  
  
    
  
  
  
    
    Sorry, something went wrong.
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.


  
  


          
      
  
    
    
            HeahDude reacted with thumbs up emoji
      
        
            
    All reactions
  


          
              
                👍
                  1 reaction
+    The index file (for example ``Resources/doc/index.rst`` or
     ``Resources/doc/index.md``) is the only mandatory file and must be the entry
     point for the documentation. The
     :doc:`reStructuredText (rST) </contributing/documentation/format>` is the most
-          Expand Down