[DOC] Add information about how to contribute

[lionelkusch]

This is based on the PR #304 and #301.

I added some files for improving the documentation based on Contribution files from different projects:

• nilearn: https://nilearn.github.io/stable/development.html
• scikit-learn: https://scikit-learn.org/stable/developers/contributing.html
• skrub: https://skrub-data.org/stable/CONTRIBUTING.html
• nest: https://nest-simulator.readthedocs.io/en/stable/developer_space/index.html
• brain2: https://brian2.readthedocs.io/en/stable/
• moabb: https://github.com/NeuroTechX/moabb/blob/develop/CONTRIBUTING.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.08%. Comparing base (379fce6) to head (29ee470).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #307   +/-   ##
=======================================
  Coverage   98.08%   98.08%           
=======================================
  Files          22       22           
  Lines        1148     1148           
=======================================
  Hits         1126     1126           
  Misses         22       22           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jpaillard]

Suggested change

	dev/CONTRIBUTING
	dev/index
	generated/gallery/examples/index
	generated/gallery/examples/index
	dev/CONTRIBUTING
	dev/index

Not 100% sure this is the place to modify it but it would be preferable if the navigation bar displays: API | examples | contributing / more (dropdown menu)

[lionelkusch]

Yes, it's the right place for the modification of the position of the head navigation page.

The drop menu is defined by the number of elements to show need to be modified in the configuration file.
I updated it and told me if it's what you expected.

[jpaillard]

Yes, sorry if I did not express myself clearly. The point was to have API and exemples as the two first elements.
I let you decide the number of elements before dropdown.

[jpaillard]

I also suggest to add the install before the API.

[lionelkusch]

The installation is on the main page.
I don't see the point to add it to the header navigator.
For going more in this direction, I was including Quick start for contributing but @bthirion seems not happy with it.

[bthirion]

Looking at the result, I find that the contributors page is just a bunch of links toward other pages. I don't really like it, because it requires readers to click again and again. I'd rather have the information concentrated on few, dense pages.

[bthirion]

For instance, one big page for Quick start for contributing and one for another one for advanced topics.

[lionelkusch]

Looking at the result, I find that the contributors page is just a bunch of links toward other pages. I don't really like it, because it requires readers to click again and again. I'd rather have the information concentrated on few, dense pages.

What is the page "contributors page"?

For instance, one big page for Quick start for contributing and one for another one for advanced topics.

Do you want to merge Quick start for contributing and How to contribute to HiDimStat? page?

For the structure of the development documentation, I don't know what is the best way to organise the developer documentation.

[bthirion]

I ahve a bunch of minro comments. LGTM overall.

[bthirion]

Isn't there a simple command to get this information ? Otherwise people won't do it properly (or won't do it at all).

[lionelkusch]

It will depend on the package manager, but in your case, pip list should be enough.

I add a line for indicated it.

[lionelkusch]

I can create a GitHub template for helping the user to create issues.

[lionelkusch]

I want to include some tests related to the figure generated in the examples.
For it's important because the change in the figures can imply a change in the text of the examples.
I open an issue regard to it #312 .

[lionelkusch]

Looking at the result, I find that the contributors page is just a bunch of links toward other pages. I don't really like it, because it requires readers to click again and again. I'd rather have the information concentrated on few, dense pages.

What is the page "contributors page"?

For instance, one big page for Quick start for contributing and one for another one for advanced topics.

Do you want to merge Quick start for contributing and How to contribute to HiDimStat? page?

For the structure of the development documentation, I don't know what is the best way to organise the developer documentation.

@jpaillard @bthirion
Do you have a suggestion for organising the documentation for the developers?

From my side, I don't like to have a unique page but if you tell me that it is best, I do it.

[bthirion]

The current solution where the Quick start in one page and the how to contribute is a menu, is fine.
I think that the dev doc is not the priority for now. The narrative doc is much more important. In all packages I know the dev doc was written way after the narrative doc.

[lionelkusch]

I agree that the narrative documentation is more important. For your other packages, I think that the library was developed by the users of it, in case it's more natural to define create the narrative documentation at first . In my case, I don't use it and mainly develop it; it's more natural for me to create the developer’s documentation at first.

As I mentioned in issue #306, it's really difficult for me to create this type of documentation. I will need a real practical case for starting it. The only solution that I find for the moment is to organise a workshop on this topic.

[bthirion]

As I mentioned in issue #306, it's really difficult for me to create this type of documentation. I will need a real practical case for starting it. The only solution that I find for the moment is to organise a workshop on this topic.

Yes, that's the right way to proceed.