User Documentation

Anything related to PR, release planning and any other non-technical idea how to move the project forward should be discussed here.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

Absolutely, that is why I offered alternatives. There are tools out there that helps. I use PyCharm's markdown and ReST plugins for example. I'm sure sublime and notepad++ have plugins as well.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

I think I've found the solution. I've downloaded PyCharm just to try out. I generally like text editors for their simplicity and lack of distractions, but I figured a plugin to view sphinx would be really helpful. I think this may be what I recommend in my guide because it works with GitHub nicely, which eliminates having them use the shell to commit and push. It also has some sphinx functionality built it so that takes care of that. (Side question, if people install PyCharm, do they still need to install sphinx separately?) But what makes everything a lot easier, is I can set conf.py to be ignored by version control, so I can have people safely just comment out the breathe line. Do you see any reason I should try a better solution? The only hazard I see is if we make a change to conf.py down the road and theirs wouldn't be updated. But even then, all they need it for is to allow sphinx to build a local preview.
psi29a wrote: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.
I don't think we really need to worry about this. For the most part, ReST is just super easy. I don't think it's too much to ask, and the duplication of work would be a constant pain. Plus, I think scrawl would be very opposed since this would normalize having documentation spread around. If it becomes a problem, we can reevaluate, but ideally anyone contributing can just spend 2-3 hours setting everything up and learning ReST.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

Sure, I'm happy with whatever works. If we comment out the need for breath/doxygen, great... no one needs to be there anyway unless they want to be helping me add autodoc entries to pick up code comments from source. ;)

My concern was that I don't think people need a full-stack (sphinx/breath/doxygen/etc) just to write documentation but that is my opinion. ReST is super easy and having something is a heck of a lot better than nothing. Worrying about formatting issues comes much later in the process I believe. We'll likely have people (editors) going through it any editing files after the fact to make sure everything looks good.

IRL, for example, content is written by journalists, reviewed and edited before being sent to layouters before it is finalized to be printed (or these days posted).

If someone wants to do _everything_ sure, install the full stack and go... but it shouldn't be a requirement just to write documentation. :)
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

I am just throwing questions here...
Seeing that conf.py is just a python script and that sphinx does not allow to set a custom conf.py file, would it be possible to add some logic so that based on some argument it would add/remove the additional extensions?
I am thinking of being able to do something like `sphinx-build -b html source build -no_breathe`,

That way we avoid having to keep track of local changes in the files. In Java you can pass any key/value variable to a process with the `-D` flag, these are accessible from any point like an ENV var without needing to set them in the shell first. Thing is I can't find a similar feature in Python.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

psi29a wrote:My concern was that I don't think people need a full-stack (sphinx/breath/doxygen/etc) just to write documentation but that is my opinion. ReST is super easy and having something is a heck of a lot better than nothing. Worrying about formatting issues comes much later in the process I believe. We'll likely have people (editors) going through it any editing files after the fact to make sure everything looks good.
Well, I'd like to avoid unnecessary parts of the stack, but I think people will be uncomfortable not being able to preview their edits. As to the formatting, I definitely foresee doing some large scale basic formatting changes, but those decisions are easier to make after we have the vast majority of content. At the same time, we need a lot of this documentation now, so it should be in some kind of usable format.
Naugrim wrote:Seeing that conf.py is just a python script and that sphinx does not allow to set a custom conf.py file, would it be possible to add some logic so that based on some argument it would add/remove the additional extensions?
I am thinking of being able to do something like `sphinx-build -b html source build -no_breathe`,
That would be even more ideal, but I was hoping to get something that will work within the built in features of PyCharm. I do think such a thing is possible, I'm just not familiar enough with Python, how exactly sphinx uses the conf.py file, or PyCharm to get it set up this way. Perhaps I should focus on other things until the weekend when I really have time to dig into all of it.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

Ravenwing wrote: That would be even more ideal, but I was hoping to get something that will work within the built in features of PyCharm. I do think such a thing is possible, I'm just not familiar enough with Python, how exactly sphinx uses the conf.py file, or PyCharm to get it set up this way. Perhaps I should focus on other things until the weekend when I really have time to dig into all of it.
Don't worry too much about it, I agree having a nice user-friendly environment is very important, but as long as the solution works for you is ok.
Honestly, I do appreciate you'r efforts, I feel I am slacking a bit with other stuff XD
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

Figured out what I want to do. I've submitted a PR to add an optional conf.py file. This way, all you have to do to get the thing to compile is

Code: Select all

sphinx-build -b html -c <nobreathe/conf.py> <source> <build>
Within PyCharm, you can just add the additional arguments into the sphinx plugin configuration and it builds. I think I've got everything easy enough for a noob to follow directions and get them set up so hopefully I'll have a tutorial for them by the end of the week.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

I have a better idea (something I've been thinking about over the weekend).

Try to import breath, if it fails, then don't use the breath module. :) I'll try to implement it today.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

Have a look at this https://github.com/OpenMW/openmw/pull/1205 8-)

This should resolve some issues. It will try to import breath and cmake python libs, if they can't be found it moves on. This means that people can write documentation and run sphinx without the libs. This should make things easier.

It will also warn users about the missing libs.

Is this OK?
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

A much more elegant solution psi29a, thanks!
Post Reply