User Documentation

Anything related to PR, release planning and any other non-technical idea how to move the project forward should be discussed here.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

psi29a wrote:

Code: Select all

virtualenv venv
source venv/bin/activate
pip install sphinx # and other deps as necessary
cd docs/source
make html
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?
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

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:

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`
Thanks for that! :)

There are also a lot of warnings, if you wish to fix those, be our guest. ;)
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

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 :D 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"]
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.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

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.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

Naugrim 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 .
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 less ;)
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.
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...
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`.
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:

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
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.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

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.
Me too!

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 :P 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.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

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:

Code: Select all

python
breathe
parse_cmake
sphinx
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

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:
No need to. We all have lifes.
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
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.
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.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

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.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

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.
Post Reply