search

mazi-project / guides

MIT License
25 stars 2 forks source link

How to Contribute Documentation? #9

Closed hellekin closed 6 years ago

hellekin commented 6 years ago

Hi,

I'm trying to solve #7, but I'm confused with the source tree, as it seems to contain build files, and has 2 source directories, one called _sources containing text files, and one called source containing .rst files.

Thank you!

panosnethood commented 6 years ago

Thanks @hellekin! Looking at previous commits, it seems that it should be enough to change the .rst files. @haniavis could help on how you can build locally the documentation, but for simple changes you could already try a pull request directly changing the corresponding .rst file.

haniavis commented 6 years ago

Hi,

I just cleaned the repository from old build files.

This documentation is built using the Sphinx tool. So if you want to build locally the documentation, you should first clone the repo, then install sphinx in your machine and finally execute the following inside the guides folder: sphinx-build -b html tech/source/ /your_output_folder/ Then you will be able to see the html files in your output folder.

Now in order to push these changes to the MAZI repository, you should fork the repository, optionally create another branch, make the changes and then create a pull request.

If you think that forking and creating a pull request is too much for this (probably), you can simply create another issue with your feedback and we will merge your feedback to the repository.

panosnethood commented 6 years ago

I updated here the guidelines for contributors: https://github.com/mazi-project/guides/wiki/Contributing

Next step is to write guidelines for the contributors to the software code ...

hellekin commented 6 years ago

OK. I think there should be a Makefile to build the documentation, and the build/ directory should not be in the repository, only the sources. That would remove confusion... Maybe a Dockerfile could be there as well for people to preview the build without polluting their system with Sphinx dependencies.

hellekin commented 6 years ago

Hi @haniavis, I made #10 that should also close this issue.