[RFR] Docs restructured #53
Conversation
| @@ -63,7 +63,8 @@ instance/ | |||
| .scrapy | |||
|
|
|||
| # Sphinx documentation | |||
| docs/_build/ | |||
| docs/build/ | |||
| docs/source/usage/help_output.inc | |||
There was a problem hiding this comment.
This is generated dynamically
| docs: ## generate Sphinx HTML documentation, including API docs | ||
| rm -f docs/disruption_generator.rst | ||
| rm -f docs/modules.rst | ||
| sphinx-apidoc -o docs/ disruption_generator |
There was a problem hiding this comment.
I don't think we are ready to have auto-generated API docs. They actually look like mess and there's not much of them anyway. We can easily re-activate this later once we actually have some docstrings.
| :param experiments_path: Path to directory with definitions of experiments. | ||
| :return: 0 on success, else 1. | ||
| :rtype: int | ||
| """ |
There was a problem hiding this comment.
This is just an example of how docstring should look like for autodoc make proper use of it.
| %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% | ||
|
|
||
| :end | ||
| popd |
There was a problem hiding this comment.
I don't believe we really support Windows setup at this moment, so why even have this?
| @@ -1,38 +1,45 @@ | |||
| #!/usr/bin/env python | |||
There was a problem hiding this comment.
This has been built automatically by sphinx-quickstart, but I believe all the params are correct there.
CONTRIBUTING.rst
Outdated
| $ make docs | ||
|
|
||
| You can also let the docs be built dynamically while working on them. | ||
| You can see sphinx output in console and you can see your changes straing away in browser (that is after you hit refresh |
|
Try to build the docs from RTD first. |
|
Okay, so based on suggestion of @grafuls, I tried building this docs on RTD. I've had some problems but now it finally builds. You can check it if you visit our documentation website and switch to version Unfortunately, Travis has some problem now. It seems that one of our packages in |
|
The error message is quite funny:
Well, pluggy probably won't be <0.7 and >=0.7 at the same time. :-) The wierd thing is that I cannot reproduce this locally. Any idea on this, @grafuls ? |
|
Hint by @grafuls: |
|
Okay, so I also fixed the problem with installing sub-dependencies. TL;DR it is pipenv's problem that must be worked around a little bit until it is properly solved. You can read about it here. If you want to see just the solution, check this comment and let's say the next five comments. The work-around is here: e8a4eee |
So what's the point of this PR? Let's go through it:
disruption_generator --helpoutputI generally think that the current structure is cleaner and it is easier for future contributors to just jump in and extend the documentation. Let me know what do you think.