![]() The same holds true for HTTP verbs: use POST to create, DELETE to delete. Be consistent! If you can remain consistent in naming conventions and stick with existing standards for behavior, you’ll have to document an item only once … if at all! For example, for HTTP status codes: don’t bend meanings, don’t add new codes: “Don’t force users to understand your slightly eccentric view of the world.” Don’t go off the beaten path: 200 means OK. Good design decisions make it easier to document your APIs. Earned through hard-won experience, here are some tips Andy provided to help you create RESTful API documentation your users will love. Your final _build/html/index.If APIs are eating the world (as InformationWeek suggests), you can think of API documentation as recipes, a crucial part of making your API easy to understand and easy to use. Just as chefs rely on well-written recipes to create wonderful dishes, you need to create API documentation that is informative, succinct, and easy to read so other developers can cook up something wonderful using your APIs.Īndy Wilkinson, Spring IO Platform lead at cloud-native platform company Pivotal, provided great tips in his presentation “Documenting RESTful APIs” at SpringOne2GX in Washington, D.C., last month. Thanks to Daniel Heater for correcting bugs in these. toctree:: :maxdepth: 2 :caption: Contents: Indices and tables = * :ref:`genindex` * :ref:`modindex` * :ref:`search` Table of Contents ^^^^^^^^^^^^^^^^^. Welcome to C++ Sphinx Doxygen Breathe's documentation! =. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. C++ Sphinx Doxygen Breathe documentation master file, created by sphinx-quickstart on Wed Jun 24 11:46:27 2020. doxygenfile:: cpp_doxygen_sphinx.hpp :project: C++ Sphinx Doxygen Breatheįinally, edit the `index.rst` in the **main** directory such that it can find these files. toctree:: :maxdepth: 2 :glob: *Īnd cpp_doxygen_sphinx.rst with contents. In the docs_sphinx directory, make a new folder: mkdir apiĪdd two files to the api folder: index.rst with contents. In Sphinx you can be more “flexible” (read: tedious), which means you need to add sources manually…. Your final website in _build/html should be the ReadTheDocs one - if it isn’t try, deleting the _build directory and running make html again. You should see output from both Doxygen and Sphin in the command line. We added the language for highlighting code as c++.We added a bunch of extensions including breathe.The first part under `Path setup` runs Doxygen.Edit your conf.py such that the complete file reads: Now we will need to hook up the output from Doxygen to Sphinx via Breathe. You can fire it up and see that it works: doxygen Doxyfile.inĬheck _build/html/index.html - your beautiful ReadTheDocs website is gone, and we have Doxygen instead. GENERATE_XML = YES - make sure you turn this on.INPUT = “./include/” - the input header files.OUTPUT_DIRECTORY = “_build” - the output directory.GENERATE_LATEX = NO - it’s on by default, but you might not need it.VERBATIM_HEADERS = NO- otherwise sources for header files will be included in the docs - I usually find this redundant.PROJECT_NAME - self explanatory, here we set `C++ Doxygen Sphinx Breathe`.Run in the docs_sphinx directory: doxygen -g mv Doxyfile Doxyfile.inĮdit the following fields in Doxyfile.in: Now for the heart of the matter: we are going to use Breathe to hook up the output from Doxygen to your Sphinx nonsense.įor clarity we will start over, but you could copy over the Doxygen.in file from the last part and make some edits. Now _build/html/index.html should look better! Hook it up to your C++ code via output from Doxygen via Breathe You could fill out the bottom three options later. To refresh your memory, we had for the contents of the header file: Setting up the projectįrom the previous post, your project should already have the following directories and files: CMakeLists.txt docs_doxygen/Doxyfile.in include/cpp_doxygen_sphinx.hpp src/cpp_doxygen_sphinx.cppīut: The only parts you will really need for the next part are: include/cpp_doxygen_sphinx.hpp src/cpp_doxygen_sphinx.cpp If you aren’t on a Mac, I don’t know, somehow figure out those installations with your favorite package manager. Any other Sphinx configuration packages you may want, e.g.:.Make sure you have all the needed tools installed: In the last post, we already showed how to get warnings for documentation. Note that we won’t incorporate this into the CMake process. This next part will be about getting an actually good looking website out there using Doxygen/ Sphinx/ ReadTheDocs/ Breathe (oof). Setting up Doxygen/Sphinx/ReadTheDocs/Breathe
0 Comments
Leave a Reply. |