Docs building instructions

[jurijsk]

I'm very new to Python and tooling surrounding it, and making use of the library without documentation online is difficult.

A see that the repo contains /docs folder with docs that are supposed to be build with sphinx, but I can not get it to work. I installed sphinx-build and a bunch of libraries it said it can not import, but stuck at

PandocMissing in example_notebooks\anachronism.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html

even though I did both installed pandoc executable and did pip install pandoc.

Would love to know what is the process here, and the steps to follow.

OS: Windows Lib verions 0.0.48

[jurijsk]

UPDATE: got it to built.

used .\docs\make.bat html.

Since I have no idea how to get started I've installed all missing packages manually, but you apparently can use 'pip install .[docs]'. This will not make it work, but take you closer. You also have to install pandoc, and it only worked after I did it with conda.

Not without warning:

[..]\guidance\docs\api.rst:49: WARNING: autosummary: failed to import guidance.llms.transformers.StableLM.
Possible hints:
* AttributeError: module 'guidance.llms.transformers' has no attribute 'StableLM'
* ModuleNotFoundError: No module named 'guidance.guidance'
* ImportError:
* AttributeError: module 'guidance' has no attribute 'guidance'
* ModuleNotFoundError: No module named 'guidance.llms.transformers.StableLM'
[..]\guidance\docs\api_examples.rst:32: WARNING: toctree glob pattern 'example_notebooks/api_examples/llms/*' didn't match any documents
[..]\guidance\docs\example_notebooks\chatgpt_vs_open_source_on_harder_tasks.ipynb:2561: WARNING: Explicit markup ends without a blank line; unexpected unindent.
[..]\guidance\docs\example_notebooks\chatgpt_vs_open_source_on_harder_tasks.ipynb:2676: WARNING: Explicit markup ends without a blank line; unexpected unindent.
[..]\guidance\docs\example_notebooks\chatgpt_vs_open_source_on_harder_tasks.ipynb:3058: WARNING: Explicit markup ends without a blank line; unexpected unindent.
[..]\guidance\docs\example_notebooks\chatgpt_vs_open_source_on_harder_tasks.ipynb:2606: ERROR: Unknown target name: "guidance_interface_target".
[..]\guidance\docs\example_notebooks\chatgpt_vs_open_source_on_harder_tasks.ipynb:2721: ERROR: Unknown target name: "guidance_interface_target".
[..]\guidance\docs\example_notebooks\chatgpt_vs_open_source_on_harder_tasks.ipynb:3070: ERROR: Unknown target name: "guidance_interface_target".
[..]\guidance\guidance\library\_each.py:docstring of guidance.library._each.each:17: ERROR: Unexpected indentation.
[..]\guidance\docs\index.rst:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... [..]\guidance\docs\example_notebooks\anachronism.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\api_examples\llms\transformers\LLaMA.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\applications\jsonformer.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\art_of_prompt_design\prompt_boundaries_and_token_healing.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\art_of_prompt_design\use_clear_syntax.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\chat.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\chatgpt_vs_open_source_on_harder_tasks.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\guaranteeing_valid_syntax.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\guidance_acceleration.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\pattern_guides.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\proverb.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\token_healing.ipynb: WARNING: document isn't included in any toctree
[..]\guidance\docs\example_notebooks\tutorial.ipynb: WARNING: document isn't included in any toctree

but it's something.

Fun ride, I did not wanted :)

[Baael]

Thanks. I also have no clue how to start, I managed to accomplish something, but I have the feeling that developers increasingly expect you to read their minds. From project to project, it's getting worse, only mental shortcuts, or assumptions that something is clear. (such a dev-bias)

[jurijsk]

Hey, we are getting a peace of software for free plus its early days. Things will get better. Glad that if my comment helped.

[Baael]

It is not for free, it is part of ecosystem.

[marcotcr]

You can access the docs here (this should have been on the readme, I'll add it).