[doc] Link to Contribution Guideline page is not valid.

[vjain641]

Referred to the Introduction section. Here Community contribution guidelines link mentioned is not valid, opening which it says Maze found. I also checked whether the correct link is provided on stable and latest release but result is same. Could you provide a reference to the Cygnus community contribution guidelines?

[fgalan]

This seems to be the right one: https://github.com/telefonicaid/fiware-cygnus/blob/master/doc/contributing/contributing_guidelines.md

It would be great if somebody is able to fix it (@jason-fox ?) so it also renders correctly at RTD. Thanks!

[jason-fox]

If you run the documentation from the command line, you can see that several pages such as the contributing_guidelines.md are not found within the RTD Documentation. The fix would be to either:

• Add the missing pages to the mkdocs.yml if the page should be in the documentation
• Remove the link if the page should not be in the documentation.

mkdocs serve

INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
WARNING -  The page "index.md" contained a hyperlink to "../doc/contributing/contributing_guidelines.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-common/installation_and_administration_guide/introduction.md" contained a hyperlink to "contributing/contributing_guidelines.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-common/installation_and_administration_guide/yafs.md" contained a hyperlink to "cygnus-common/installation_and_administration_guide/runninh_as_process.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-common/installation_and_administration_guide/yafs.md" contained a hyperlink to "cygnus-common/installation_and_administration_guide/running_as_service.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/installation_and_administration_guide/configuration_examples.md" contained a hyperlink to "cygnus-ngsi/flume_extensions_catalogue/ngsi_mongo.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/installation_and_administration_guide/configuration_examples.md" contained a hyperlink to "cygnus-ngsi/flume_extensions_catalogue/ngsi_sth.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_cartodb_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_ckan_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_dynamodb_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_dynamodb_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_dynamodb_sink.md" contained a hyperlink to "ngsi_grouping_interceptor.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_kafka_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_hdfs_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_mongo_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_mysql_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_postgresql_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_sth_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_test_sink.md" contained a hyperlink to "ngsi_rest_handler.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-ngsi/flume_extensions_catalogue/ngsi_grouping_interceptor.md" contained a hyperlink to "cygnus-ngsi/flume_extensions_catalogue/deprecated_and_removed.md" which is not listed in the "pages" configuration. 
WARNING -  The page "cygnus-twitter/quick_start_guide.md" contained a hyperlink to "cygnus-twitter/user_and_programmer_guide/README.md" which is not listed in the "pages" configuration. 

[fgalan]

Should contribution guidleines be included in RTD manual? I tend to think in RTD as documentation for "final users" of the component...

In fact, in the Orion repository Contribution Guidelines and Development Manual are not included in RTD.

[jason-fox]

• The user guide should be just that - How to run commands in the product - and nothing else
• The admin guide should be just that - How to configure and install the product - and nothing else

Additional subjects such as Contribution Guidelines, testing policies, code of conduct have their place (and should be found within the docs directory IMHO, but shouldn't be indexed as part of RTD styled documentation. It makes the documentation more difficult to read.

• If I wanted to contribute I'd be happy to read the guidelines in markdown files on GitHub not RTD
• If I just want to use the product as is I can just use RTD and ignore GitHub altogether

BTW GitHub have a Contribution Guidelines Policy - we should follow it - the file should be called CONTRIBUTING.MD and be placed in root or \docs