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:
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.
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.
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.
I was thinking to update the existing wiki page (developer [NethServer Wiki]) 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
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.
@giacomowrote 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.
