Documentation issue - sphinx execution

[rojalator]

I might be being foolish, but I can see no way to generate the documentation using sphinx without Enki - for example, there is no example Makefile, nor actual instructions for generating the documentation (we do not use Enki, but pycharm). Am I missing something in the documentation? Merely adding to conf.py (as stated) does not result in the documents being generated. If CodeChat_server is required, then some instructions for that would help.

[bjones1]

There are two approaches:

• If you want to use CodeChat but not the CodeChat System, you can invoke the build manually -- for example, sphinx-build -d _build\doctrees . _build would build a typical Sphinx / CodeChat setup.
• Using the CodeChat System, you can:
  • Build automatically every time you save a file in your IDE by invoking CodeChat_Server watch.
  • Have your IDE build by invoking the CodeChat_Server render on a specific key sequence.
  • Build manually (see CodeChat_Server build).

[bjones1]

I've dropped support for Enki and instead now support Visual Studio Code. It's quite possible to support other IDEs as well, such as PyCharm -- I can help if you're interested in writing a plug-in.

[rojalator]

Thanks - a plugin would be handy eventually: I've used the vscode one but also could not get that to render all the files.

I've tried the CodeChat_server render / build but the output, although html, did not match that of sphinx: it would seem (I'm guessing) that outputting to rst and having sphinx render that might work better.

I was expecting (perhaps wrongly) a step akin to sphinx-apidoc:

codechat-doc -o source/ ../projectname

or similar.

I think the issue is with the documentation - on readthedocs there's codechat AND codechat-system. The former does not detail (at least I could not find it) how to run the sphinx-build and also does not really tell a reader that it's codechat-system that they also might need to consult. The 'use' link on codechat-system points one to... codechat. I did finally find 'run_sphinx.bat' which tells me to run against _build\doctrees - however, that just builds whatever is in there (apidoc output as it happens) it doesn't tell codechat to actually do anything. Note, I have conf.py set up as detailed (at least I think I have!).

(I'm trying to assist here, coming in as a new user, not just moaning).

[bjones1]

Thanks for the feedback -- the docs are a bit scattered, and I need to rewrite this.

CodeChat_Server render should build HTML -- it just invokes Sphinx (or whatever renderer is specified in the CodeChat config file).

[rojalator]

Apologies (again) if my tone sounds querulous: it's not, I'm just trying to explain my problems with the documentation.

I think the problem with render is that it leaves a running server around (I have to 'stop' it afterwards - makes writing a Makefile interesting), it asks for an ID (?) and then, although I tell it the path (docs/source in this case) tells me that the parent (docs/) doesn't contain a conf.py (docs/source does). It also looks for _build/source although in my case sphinx is set up to use separate build/ and source/ directories.

Configuration error: [config directory doesn't contain a conf.py file (/xxx/docs) /xxx/docs/source:: ERROR: CodeChat renderer - unable to find the HTML output file /xxx/docs/_build/source. If I point it to just docs/ I get the same.

'build' states that it will build and save to disc (but not where) nor how CodeChat 'project' files are determined (nor indeed what constitutes a project). Is it something in codechat_config.yaml?

[rojalator]

As an aside, I've previously use pycco and pdoc. I've moved from pdoc to sphinx and am hoping to replace pycco with CodeChat.

[bjones1]

Apologies (again) if my tone sounds querulous: it's not, I'm just trying to explain my problems with the documentation.

No problem -- I always appreciate feedback.

I think the problem with render is that it leaves a running server around (I have to 'stop' it afterwards - makes writing a Makefile interesting),

From a Makefile, call CodeChat_Server build <file_to_build>. If the file to build is a part of the project, it will rebuild the project if that file is out of date. The purpose of CodeChat_Server render is to keep the server running so an IDE can call it on a regular basis (after a source file is saved, typically).

it asks for an ID (?)

The ID for a render allows you to have multiple windows/IDEs open -- it's an arbitrary number you choose. For example, you might pick ID 1 for your main PyCharm window, ID 2 for a second PyCharm, and ID 3 for Notepad++.

and then, although I tell it the path (docs/source in this case) tells me that the parent (docs/) doesn't contain a conf.py (docs/source does). It also looks for _build/source although in my case sphinx is set up to use separate build/ and source/ directories.

Configuration error: [config directory doesn't contain a conf.py file (/xxx/docs) /xxx/docs/source:: ERROR: CodeChat renderer - unable to find the HTML output file /xxx/docs/_build/source. If I point it to just docs/ I get the same.

'build' states that it will build and save to disc (but not where) nor how CodeChat 'project' files are determined (nor indeed what constitutes a project). Is it something in codechat_config.yaml?

Take a look at this CodeChat configuration file -- you need to tell Sphinx about your particular setup. The config file supplied with the Sphinx template selects a (default) souce_path = ., an output_path = _build, and an equivalent of args = {sys.executable} -m sphinx {source_path} {output_path}. Change these values and also add -c path_to_conf_py and it should work for you.

[rojalator]

Ah ha! - the codechat_config.yaml that I had, had a different set of parameters (and also stated (c) 2012-2020, so was likely older). Now I just need to work out how, exactly, Sphinx is supposed to call this - or is it the other way around.

I'd note that I don't find Sphinx's documentation particularly enlightening either.

[rojalator]

Actually, I'm now further puzzled: how is the yaml file suitable for Sphinx as it reads conf.py?

[bjones1]

My CodeChat System reads the YAML file, using that to determine how to run Sphinx. (It can also run other builders, such as doxygen, mkdocs, etc.) The Sphinx options are mostly set in Sphinx's conf.py.