Updating static docs

[kristiankyvik]

This PR replaces #993 to address task 3 of this issue: #990

The focus of this PR is on:

• Addressed all errors and warnings in the sphinx build - we now get a clean build!
• Removing a lot of the outdated static documentation since we want to rely mostly on the automatically generated API reference
• Created a cleaner structure to the static docs that we can build on top of
• Updated docs to ensure it is consistent with the main repo readme

[kristiankyvik]

@ATheorell and @AntonOsika I would love to get a review on this one so that we can get it merged.

[ATheorell]

Great work, we are now down to only 3 warnings! That is a massive improvement.

From my point of view, you could cut down on static docs even harder. In particular, I would kill the part about "customizing steps", which is outdated. I would probably also remove the part about the "core components" since they are relatively understandable in the API reference too, but this part is now correct so, it could also stay for now :)

[ATheorell]

As requested in the meeting, here comes the full build log. I'm running Ubuntu 22 LTS

$ make html
Running Sphinx v7.2.6
making output directory... done
[autosummary] generating autosummary for: DOCS_BUILDING.md, api_reference.rst, code_conduct_link.rst, contributing_link.rst, custom_steps.md, disclaimer_link.rst, index.rst, installation.rst, introduction.md, open_models.md, quickstart.rst, roadmap_link.rst, terms_link.rst, tracing_debugging.md, windows_readme_link.rst
[autosummary] generating autosummary for: /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.cli_agent.CliAgent.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.collect.collect_and_send_human_review.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.collect.collect_learnings.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.collect.send_learning.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.file_selector.DisplayablePath.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.learning.ask_collection_consent.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.learning.ask_for_valid_input.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.learning.check_collection_consent.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.learning.extract_learning.rst, /home/axel/Software/gpt-engineer-dev/docs/applications/gpt_engineer.applications.cli.learning.get_session.rst, ..., /home/axel/Software/gpt-engineer-dev/docs/core/gpt_engineer.core.default.steps.setup_sys_prompt_existing_code.rst, /home/axel/Software/gpt-engineer-dev/docs/core/gpt_engineer.core.diff.count_ratio.rst, /home/axel/Software/gpt-engineer-dev/docs/core/gpt_engineer.core.diff.is_similar.rst, /home/axel/Software/gpt-engineer-dev/docs/core/gpt_engineer.core.files_dict.FilesDict.rst, /home/axel/Software/gpt-engineer-dev/docs/core/gpt_engineer.core.files_dict.file_to_lines_dict.rst, /home/axel/Software/gpt-engineer-dev/docs/core/gpt_engineer.core.version_manager.BaseVersionManager.rst, /home/axel/Software/gpt-engineer-dev/docs/tools/gpt_engineer.tools.custom_steps.clarified_gen.rst, /home/axel/Software/gpt-engineer-dev/docs/tools/gpt_engineer.tools.custom_steps.get_platform_info.rst, /home/axel/Software/gpt-engineer-dev/docs/tools/gpt_engineer.tools.custom_steps.lite_gen.rst, /home/axel/Software/gpt-engineer-dev/docs/tools/gpt_engineer.tools.custom_steps.self_heal.rst
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'colon_fence'}, disable_syntax=[], all_links_external=True, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 15 source files that are out of date
updating environment: [new config] 76 added, 0 changed, 0 removed
reading sources... [100%] windows_readme_link
/home/axel/Software/gpt-engineer-dev/docs/index.rst:21: WARNING: toctree contains reference to nonexisting document 'docs_building'
/home/axel/Software/gpt-engineer-dev/docs/introduction.md:6: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/axel/Software/gpt-engineer-dev/docs/DOCS_BUILDING.md: WARNING: document isn't included in any toctree
done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] windows_readme_link
generating indices... genindex py-modindex done
highlighting module code... [100%] gpt_engineer.tools.custom_steps
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 3 warnings.

The HTML pages are in _build/html.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

❗ No coverage uploaded for pull request base (main@301a920). Click here to learn what that means.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1028   +/-   ##
=======================================
  Coverage        ?   84.96%           
=======================================
  Files           ?       25           
  Lines           ?     1237           
  Branches        ?        0           
=======================================
  Hits            ?     1051           
  Misses          ?      186           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kristiankyvik]

Hi @ATheorell, thanks for your comment + sharing the output of the build.

As followed your suggestion and removed:

• The core components section
• The custom steps section

Please let me know if there are other sections we should remove (e.g. windows setup, tracing and debugging).

Regarding the three remaining warnings, its strange, some of the warnings you shared make references to files that have been renamed.

I have pasted the output I see locally, clean of any errors.
make_html_output.txt

Do you see the same error if you:

• Delete all the folders with generated docs (_build, applications, benchmark, core, tools)
• Run the python create_api_rst.py
• Run the make html

[ATheorell]

Thanks for the fixes!

I'm now left with 2 warnings

/home/axel/Software/gpt-engineer-dev/docs/index.rst:20: WARNING: toctree contains reference to nonexisting document 'docs_building'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/axel/Software/gpt-engineer-dev/docs/DOCS_BUILDING.md: WARNING: document isn't included in any toctree

..and I also have a fix for it! There is a reference to docs_building.md, whereas the files is called DOCS_BUILDING.md in all caps. I guess that you are running windows? Unix is case sensitive. Renaming the file removes the warning. I will merge your PR and fix this myself.

Thanks a lot for saving the docs. Now they are both useful and easy to maintain.