Developer manual housekeeping

Just one proposal, please tell me your opinion!

I’m working on ns7 and a lot of pages in the Developer manual need to be updated. As said in the past it would be great to keep the module docs and code together, in the same git repo (same branch, same commit, same pull request…).

I’d like to move module pages from the Developer manual to the respective git repo on GitHub, like README.rst files. It’s a simple process, just a file mv.

Some sections of the Developer manual are generic, and do not fit a specific module. I’m thinking about “Development process” or “RPM package rules”. I’d like to move them to http://wiki.nethserver.org.

I asked @giacomo to kindly test the RST plugin on that Dokuwiki instance.

I started a new thread because this was really long:

/cc @docs_team

1 Like

IMHO they should stay in the developer manual, why…because they can be (badly) modified in the wiki or missed by those who want to read the developer manual and therefore build rpms.

Concerning the move to github, I suppose that the readthedoc will stay active for consulting the documentation.

Of course, this change would affect only the ns7 branch. All material related to nethserver 6.x remains in place.

Hi,

Personally, I love the Sphynx plateform. For one reason, you can make pdf book, epub book…
I think the Developper manual as a refence book can stay on the Sphinx plateform and for other stuff let the same stuff on the wiki. The two plateform are for two distincts purposes.

so, no more readthedoc…I really don’t like the template of github, and moreover I really don’t like anymore github like I did in the past :slight_smile:

The power concentration is never good, we have had a bad example with sourceforge

About module docs, I want to remark a “git repo” does not mean “GitHub”. We are free to pick other tools if we want.

1 Like

Please, @Jim @stephdl (and anyone else…) this is the point for me, developer. It’s a must-have, if we like up-to-date documentation.

I agree that it won’t change a lot, documentation is already on github but in another repository. The only thing for what I want to be really prudent, is the fragmentation of the documentation. All developer content must (should) be in one place

I think I understand your concern; “one place” for me means the module git repo because code and its doc must be together to ease maintenance. As a developer, a git clone must be enough to have both. As an admin the documentation inside module git repo should not be interesting. For admins everything must be (hopefully) in one place, too (this is another story).

Moreover, even if I move doc inside respective module git repo, I can build a website that shows all the docs together; there is plenty of ways to do it.

1 Like

I was thinking to update the existing wiki page (http://wiki.nethserver.org/doku.php?id=developer) and re-create the developer manual index pointing to the READMEs inside the github project.

I would like to know feelings and thoughts from the whole @docs_team :slight_smile:

Agree with all of the above.
My thinking is simple, It would be easy to maintain docs for the @dev_team with the aim of keeping them updated so I agree with @davidep’s proposal.
Plus, I really like the idea of gathering all docs in a single place like the wiki, people should use a single "search box"
http://wiki.nethserver.org/doku.php?id=developer
We need to get right on that.

I have no problem to get the documentation in the wiki, but some specific documentation must be protected about edit of users. Even if it is against the spirit of a wiki.

Imagine the worse things that it can happen, if a simply user edit the documentation on how build a rpm…just a thought.

EDIT: in another hand we can protect that kind of page, and so restrict the edit to power user.

1 Like

@giacomo is a PR needed to change this documentation?

Yes, if we move the documentation to github, a Pull Request is always needed.

Only the index inside the wiki will be editable without special permissions.

Can you show us a brief preview? Just so we can get a better idea

Index page (to be improved): http://wiki.nethserver.org/doku.php?id=developer
SOGo devel doc: https://github.com/NethServer/nethserver-sogo/blob/master/README.rst

1 Like

Personnally, I like wiki for online consult…
And I like “handbook” for read tranquilly far from the screen…

The two are usefull

Me, @giacomo and @Stll0 started to move .rst files from nethserver-docs to the respective repositories.

For instance

https://github.com/DavidePrincipi/nethserver-mail-filter/blob/v7/README.rst

@giacomo wrote a script that imports that files back into the Dev manual on ReadTheDocs. As a first step we’ll adopt a process similar to translations: we pull sources from modules repositories and push the results into a single repo.

2 Likes