diff --git a/.gitignore b/.gitignore index 2842192..ec272c5 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,9 @@ CMakeCache.txt install docs/_build +# Python files +*env* + .cproject .project .dir-locals.el diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 9b67c7b..67d4c41 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -22,7 +22,7 @@ if (DOXYGEN_FOUND) # Doxygen configuration set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) - set(DOXYGEN_TYPEDEF_HIDES_STRUCT NO) + set(DOXYGEN_TYPEDEF_HIDES_STRUCT YES) set(DOXYGEN_EXTRACT_ALL YES) set(DOXYGEN_EXTRACT_STATIC YES) set(DOXYGEN_STRIP_CODE_COMMENTS NO) @@ -74,4 +74,14 @@ if (SPHINX_FOUND AND DOXYGEN_FOUND) add_sphinx_builder(sphinx-spelling spelling) add_sphinx_builder(sphinx-linkcheck linkcheck) + # Zip the documentation + message("c-open revision: ${CANOPEN_GIT_REVISION}") + add_custom_command( + TARGET sphinx-html POST_BUILD + COMMAND zip -FS -r copen_docs_${CANOPEN_GIT_REVISION}.zip sphinx/html/ > /dev/null + COMMAND echo "The Sphinx HTML and ZIP files are located in ${CMAKE_CURRENT_BINARY_DIR}" + BYPRODUCTS ${CMAKE_CURRENT_BINARY_DIR}/copen_docs_${CANOPEN_GIT_REVISION}.zip + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Zipping HTML documentation") + endif() diff --git a/docs/README.txt b/docs/README.txt new file mode 100644 index 0000000..1d230cb --- /dev/null +++ b/docs/README.txt @@ -0,0 +1,12 @@ +To build the documentation, it is important to use the sphinx-build script +installed in your virtual environment. +Use CMAKE_IGNORE_PATH to prevent cmake from using a script installed elsewhere + +Run these commands (adapt to your needs): + +python3 -m venv myvenv +source myvenv/bin/activate +pip3 install -r docs/requirements.txt + +cmake -B build -DCMAKE_IGNORE_PATH:PATH=$HOME/.local/bin +cmake --build build/ --target sphinx-html diff --git a/docs/api_reference.rst b/docs/api_reference.rst index 8a405ca..7c6a3bb 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -23,30 +23,30 @@ Callbacks Structs -------- -.. doxygenstruct:: co_obj +.. doxygenstruct:: co_obj_t :members: :undoc-members: -.. doxygenstruct:: co_entry +.. doxygenstruct:: co_entry_t :members: :undoc-members: -.. doxygenstruct:: co_default +.. doxygenstruct:: co_default_t :members: :undoc-members: -.. doxygenstruct:: co_cfg +.. doxygenstruct:: co_cfg_t :members: :undoc-members: Enums ------ -.. doxygenenum:: co_sdo_abort -.. doxygenenum:: co_state -.. doxygenenum:: co_nmt_cmd -.. doxygenenum:: co_otype -.. doxygenenum:: co_dtype -.. doxygenenum:: od_event -.. doxygenenum:: co_store -.. doxygenenum:: co_mode +.. doxygenenum:: co_sdo_abort_t +.. doxygenenum:: co_state_t +.. doxygenenum:: co_nmt_cmd_t +.. doxygenenum:: co_otype_t +.. doxygenenum:: co_dtype_t +.. doxygenenum:: od_event_t +.. doxygenenum:: co_store_t +.. doxygenenum:: co_mode_t diff --git a/docs/conf.py b/docs/conf.py index 9973986..a1dd5f5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,22 +6,29 @@ # -- Path setup -------------------------------------------------------------- -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import pathlib +import re +import sys + +import os +pathobj_docs_dir = pathlib.Path(__file__).parent.absolute() +pathobj_rootdir = pathobj_docs_dir.parent.absolute() + # -- Project information ----------------------------------------------------- +try: + cmakelists_contents = pathobj_rootdir.joinpath("CMakeLists.txt").read_text() + versiontext_match = re.search(r"CANOPEN VERSION ([\d.]*)", cmakelists_contents) + version = versiontext_match.group(1) +except: + version = "unknown version" + project = 'c-open' -copyright = '2022, RT-Labs AB' +copyright = '2023, RT-Labs AB' author = 'RT-Labs AB' - # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -32,7 +39,6 @@ "recommonmark", "sphinx_copybutton", "sphinx_jinja", - "sphinx_rtd_theme", "sphinx.ext.autosectionlabel", "sphinx.ext.graphviz", "sphinxcontrib.kroki", @@ -40,11 +46,12 @@ "sphinxcontrib.spelling", ] + # Spelling spelling_word_list_filename = "spelling-wordlist.txt" # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["../../_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -57,17 +64,28 @@ # -- Options for HTML output ------------------------------------------------- -# TODO Fine-tune the CSS to adjust logo and API documentation appearance -html_theme = "press" +html_context = { + "default_mode": "light" +} + +html_theme = "sphinx_book_theme" +html_theme_options = { + "show_nav_level": 3, + "home_page_in_toc": True, + "use_repository_button": True, + "use_fullscreen_button": False, + "navbar_end": ["navbar-icon-links"], + "use_download_button": False, + "repository_url": "https://github.com/rtlabs-com/c-open", +} + html_last_updated_fmt = "%Y-%m-%d %H:%M" html_static_path = ["static"] -html_logo = "illustrations/c-open.png" +html_logo = "static/i/c-open.svg" html_show_sourcelink = False -html_copy_sources = False -html_show_sphinx = False -html_css_files = [ - "../../css/custom_rtd.css", - "css/fix_table_width.css", - "css/change_header_size.css", -] +if os.getenv("USE_EXTERNAL_CSS") is not None: + html_css_files = [ + "https://rt-labs.com/content/themes/rtlabs2020/assets/css/style.css", + "https://rt-labs.com/content/themes/rtlabs2020/assets/css/rt_custom_sphinx.css", + ] diff --git a/docs/dependencies.txt b/docs/dependencies.txt deleted file mode 100644 index fc0c531..0000000 --- a/docs/dependencies.txt +++ /dev/null @@ -1,12 +0,0 @@ -breathe==4.31.0 -codespell==2.1.0 -graphviz==0.16 -recommonmark==0.7.1 -rstcloth==0.5.2 -sphinx-copybutton==0.3.1 -sphinx-jinja==2.0.1 -sphinx-rtd-theme==1.0.0 -Sphinx==3.5.4 -sphinxcontrib-kroki==1.2.1 -sphinxcontrib-programoutput==0.17 -sphinxcontrib-spelling==7.1.0 diff --git a/docs/illustrations/c-open.png b/docs/illustrations/c-open.png deleted file mode 100644 index a706aab..0000000 Binary files a/docs/illustrations/c-open.png and /dev/null differ diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..2e93aac --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,20 @@ + +# Solve issue with missing bullet points +# See https://stackoverflow.com/questions/67542699/readthedocs-sphinx-not-rendering-bullet-list-from-rst-file +docutils==0.17.1 + +# Use versions that fit the docutils version +breathe==4.34.0 +codespell==2.2.2 +graphviz==0.20.1 +myst-parser==0.18.1 +recommonmark==0.7.1 +rst2pdf==0.99 +rstcloth==0.5.3 +sphinx_book_theme==1.0.1 +sphinx-copybutton==0.5.1 +sphinx-jinja==2.0.2 +Sphinx==5.3.0 +sphinxcontrib-kroki==1.3.0 +sphinxcontrib-programoutput==0.17 +sphinxcontrib-spelling==8.0.0 diff --git a/docs/static/css/change_header_size.css b/docs/static/css/change_header_size.css deleted file mode 100644 index 56e6635..0000000 --- a/docs/static/css/change_header_size.css +++ /dev/null @@ -1,3 +0,0 @@ -/* Reduce subheading size */ - -h3{font-size: 110%;} diff --git a/docs/static/css/fix_table_width.css b/docs/static/css/fix_table_width.css deleted file mode 100644 index 76e9a3e..0000000 --- a/docs/static/css/fix_table_width.css +++ /dev/null @@ -1,15 +0,0 @@ -/* From https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ - -/* override table width restrictions */ -@media screen and (min-width: 500px) { - - .wy-table-responsive table td { - /* !important prevents the common CSS stylesheets from overriding - this as on RTD they are loaded after this stylesheet */ - white-space: normal !important; - } - - .wy-table-responsive { - overflow: visible !important; - } -} diff --git a/docs/static/i/c-open.svg b/docs/static/i/c-open.svg new file mode 100644 index 0000000..699fb79 --- /dev/null +++ b/docs/static/i/c-open.svg @@ -0,0 +1 @@ +c-open \ No newline at end of file