The `make html` did not work for me, instead I got to render the docs using `sphinx-buid -b html source build`. Is that equivalent?psi29a wrote:Code: Select all
virtualenv venv source venv/bin/activate pip install sphinx # and other deps as necessary cd docs/source make html
User Documentation
Re: User Documentation
- psi29a
- Posts: 5362
- Joined: 29 Sep 2011, 10:13
- Location: Belgium
- Gitlab profile: https://gitlab.com/psi29a/
- Contact:
Re: User Documentation
That works too, yeah sorry... the make file is missing. I should probably make one so it is as simple as doing `make html`.
Revising steps:
Thanks for that!
There are also a lot of warnings, if you wish to fix those, be our guest.
Revising steps:
Code: Select all
virtualenv venv
source venv/bin/activate
pip install sphinx parse_cmake breathe
cd docs
sphinx-build -b html source build # so to be `make html`
There are also a lot of warnings, if you wish to fix those, be our guest.
Re: User Documentation
My installation complains if doxygen is not found. Maybe there's some dependency with it because the process renders all docs, included the C api docs.
Anyway, I got a lighweight docker image working nicely. I don't use Python, but I use Docker a lot, so for me it's much easier. Also I can get the environment ready in seconds if I change computer. I have docker in all my home machines.
I can even program a default`watch` process that renders the docs every few seconds So I can focus con writing in one screen and keep an eye for possible warnings on the other.
This is it:
One thing concerns me is that it pulls the latest versions, and those may not be the same as RDT. But still right now I don't worry about the environment.
Just to manage expectations. I have 2 things to finish first, so I won't be sending docs for at least 1 or 2 weeks.
Anyway, I got a lighweight docker image working nicely. I don't use Python, but I use Docker a lot, so for me it's much easier. Also I can get the environment ready in seconds if I change computer. I have docker in all my home machines.
I can even program a default`watch` process that renders the docs every few seconds So I can focus con writing in one screen and keep an eye for possible warnings on the other.
This is it:
Code: Select all
FROM python:3.6.0-alpine
# breathe pulls sphinx
RUN pip install breathe parse_cmake && \
apk update && \
apk upgrade && \
apk add --no-cache doxygen && \
mkdir /docs
WORKDIR /docs
VOLUME /docs
ENTRYPOINT ["/bin/ash"]
Just to manage expectations. I have 2 things to finish first, so I won't be sending docs for at least 1 or 2 weeks.
- psi29a
- Posts: 5362
- Joined: 29 Sep 2011, 10:13
- Location: Belgium
- Gitlab profile: https://gitlab.com/psi29a/
- Contact:
Re: User Documentation
Use whatever works for you.
RTD is for our releases (0.39, 0.40, 0.41, stable->0.41) and master. So whenever something is merged into master, RTD is triggered to update the docs for master. You guys don't worry about RTD, just think of that as for releases.
RTD is for our releases (0.39, 0.40, 0.41, stable->0.41) and master. So whenever something is merged into master, RTD is triggered to update the docs for master. You guys don't worry about RTD, just think of that as for releases.
Re: User Documentation
Well I'd rather come off overly helpful to someone who knows way more than I do than to stuck up to someone who knows lessNaugrim wrote:Thanks for the advice, really. Just to add some context, I am a 10 years experiences (mainly back-end) JVM developer and contributor to other GitHub projects. I am familiar with documentation tools and in fact I am finding myself enjoying a lot writing docs .
Ditto, although I don't think I'll be adding too much more than the bare minimum for non-techies to get started, because anyone else should know how to follow the more advanced guides already in existence. Also, I won't know much more than that sooooo...Naugrim wrote:Definitely. Maybe a quick start guide for non-techies, later on we can add sections for more advanced stuff.
I am advocate of "roll out and evolve", once we have the docs in GitHub is really easy to refactor and change them.
I'm getting the same error as Naugrim at the same step. I don't mind warnings as long as it builds, but right now this is what it's spitting out into the error log file:psi29a wrote:That works too, yeah sorry... the make file is missing. I should probably make one so it is as simple as doing `make html`.
Code: Select all
# Sphinx version: 1.5.1
# Python version: 2.7.10 (CPython)
# Docutils version: 0.13.1 release
# Jinja2 version: 2.9.4
# Last messages:
# Loaded extensions:
Traceback (most recent call last):
File "c:\python27\lib\site-packages\sphinx\cmdline.py", line 295, in main
opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
File "c:\python27\lib\site-packages\sphinx\application.py", line 244, in __init__
self._init_builder(self.buildername)
File "c:\python27\lib\site-packages\sphinx\application.py", line 315, in _init_builder
self.emit('builder-inited')
File "c:\python27\lib\site-packages\sphinx\application.py", line 589, in emit
results.append(callback(self, *args))
File "c:\python27\lib\site-packages\breathe\directives.py", line 835, in doxygen_hook
app.config.breathe_doxygen_config_options
File "c:\python27\lib\site-packages\breathe\process.py", line 67, in generate_xml
project_path = self.process(data.auto_project_info, data.files, doxygen_options)
File "c:\python27\lib\site-packages\breathe\process.py", line 98, in process
self.run_process('doxygen %s' % quote(cfgfile), cwd=build_dir, shell=True)
File "c:\python27\lib\subprocess.py", line 540, in check_call
raise CalledProcessError(retcode, cmd)
CalledProcessError: Command 'doxygen openmw.cfg' returned non-zero exit status 1
Re: User Documentation
Me too!Ravenwing wrote: I'd prefer to get all this to build with as few dependencies as possible so my tutorial doesn't become a list of libraries to install.
The error apprears is because Sphinx cannot find doxygen, which takes care of parsing the C files to generate the api docs. I just installed it using the default package from the package manager in Ubuntu and Alpine and in both cases worked. For Windows it will require classical download binary and install, or there's also a package for Cygwin/Babun.
If like me you don't care about the C api docs, you can disabling `breathe` here ->https://github.com/OpenMW/openmw/blob/m ... onf.py#L38. Remove that line (and the trailing comma in the previous line) and it will work.
It will work without error, but it will only render the reST files.
Eventually, to avoid doxygen, we could have separated builds (or repos) for API and user manuals, but I am not sure this is a priority right now.
Re: User Documentation
Sorry for disappearing for a while. I'm going to try and work on the tutorial more in the next couple days. Psi29a, is there some possible solution you can think of to this:
I want to be able to give total noobs a step-by-step of how to set up sphinx and github on their computer so they can contribute user docs. I want to have as few dependencies as possible, both to keep instructions simple, and to prevent needing to install a bunch of libraries the noobs will never need access to. Is there some way to have python and sphinx be the only dependencies but also be able to compile the docs directly from their github/openmw subdirectory? I don't want to have to edit the conf.py file every time I want to compile. Unless there is a way of ignoring that line from the command line, then they can just copy paste. If not, what are all the dependencies I need to specify for them to install? Right now I have:
I want to be able to give total noobs a step-by-step of how to set up sphinx and github on their computer so they can contribute user docs. I want to have as few dependencies as possible, both to keep instructions simple, and to prevent needing to install a bunch of libraries the noobs will never need access to. Is there some way to have python and sphinx be the only dependencies but also be able to compile the docs directly from their github/openmw subdirectory? I don't want to have to edit the conf.py file every time I want to compile. Unless there is a way of ignoring that line from the command line, then they can just copy paste. If not, what are all the dependencies I need to specify for them to install? Right now I have:
Code: Select all
python
breathe
parse_cmake
sphinx
Re: User Documentation
No need to. We all have lifes.Ravenwing wrote:Sorry for disappearing for a while. I'm going to try and work on the tutorial more in the next couple days. Psi29a, is there some possible solution you can think of to this:
I fear that unless changes are done all those packages are required. In a step-by-step manual you can skip Sphinx because it's installed as a dependency of breathe.Ravenwing wrote: I want to be able to give total noobs a step-by-step of how to set up sphinx and github on their computer so they can contribute user docs. I want to have as few dependencies as possible, both to keep instructions simple, and to prevent needing to install a bunch of libraries the noobs will never need access to. Is there some way to have python and sphinx be the only dependencies but also be able to compile the docs directly from their github/openmw subdirectory? I don't want to have to edit the conf.py file every time I want to compile. Unless there is a way of ignoring that line from the command line, then they can just copy paste. If not, what are all the dependencies I need to specify for them to install? Right now I have:Code: Select all
python breathe parse_cmake sphinx
For non-tech people I would totally discard using virtual machines or Docker. I think that the trick to simplify the process is using some package manager to install Python & Doxygen. That's the more complicated part. Once is done, it's just a matter of using `pip` to install the python libs listed above.
in Linux that's not an issue, main distros include Python, MacOs users can use Homebrew and Windows users can use Chocolately.
I think that if we are able to provide an installation based on a few commands that a user can just copy and paste, we can later create a script to automate everything.
- psi29a
- Posts: 5362
- Joined: 29 Sep 2011, 10:13
- Location: Belgium
- Gitlab profile: https://gitlab.com/psi29a/
- Contact:
Re: User Documentation
Or just let users write documentation how ever they want and post it somewhere. Then have someone on the team who is more savvy mark it up for ReST.
No one _has_ to use our system, I mean look at the wiki. Matter of fact, the wiki is probably a very good place for people to write documentation on and then later convert it to ReST. That could be a sane work-flow for people who don't want to deal with a software stack just to write docs.
The other thing, ReST is similar to MD (markdown), so if someone has an editor that supports either ReST or MD, then that is good enough too.
Again, I think 'the stack' is more for the whole project and RTD and that end-users and non-technical people shouldn't be bothered with all of that.
No one _has_ to use our system, I mean look at the wiki. Matter of fact, the wiki is probably a very good place for people to write documentation on and then later convert it to ReST. That could be a sane work-flow for people who don't want to deal with a software stack just to write docs.
The other thing, ReST is similar to MD (markdown), so if someone has an editor that supports either ReST or MD, then that is good enough too.
Again, I think 'the stack' is more for the whole project and RTD and that end-users and non-technical people shouldn't be bothered with all of that.
Re: User Documentation
That's true, not everyone needs to be fluent with the tools and format. But still I don't think we need to hide all details.
People can use some wysiwyg like these: http://rst.ninjs.org/ or https://www.notex.ch/editor.
People can use some wysiwyg like these: http://rst.ninjs.org/ or https://www.notex.ch/editor.