I have the following in my setup.cfg file:
[project.urls]
"Documentation" = "https://pysui.readthedocs.io"
"Bug Reports" = "https://github.com/FrankC01/pysui/issues"
My build executes without error and twine check and twine upload work without a hitch. However, the extra links do not show up in PyPi?
I think that format works only with the pyproject.toml as described at https://packaging.python.org/en/latest/tutorials/packaging-projects/#configuring-metadata . Note, the above describes how it works when using pypa's build for building, other packaging tools use their own ways to define this information.
If you prefer to use setup.cfg, you could try adding the project_urls under [metadata] like this:
[metadata]
project_urls =
Documentation = https://pysui.readthedocs.io
Bug Reports = https://github.com/FrankC01/pysui/issues
One more tip: you can check the PKG-INFO file in the created tar archive to see that the information was added correctly:
Project-URL: Documentation, https://pysui.readthedocs.io
Project-URL: Bug Reports, https://github.com/FrankC01/pysui/issues
Related
The new approach to setup a Python package is to use a setup.cfg file.
But, it's impossible to find how I can add a data_files parameters.
How I can do it?
Use package_data instead of data_files. For example if you wanted all the xml files in mypkg/templates, this would work in setup.cfg:
[options.package_data]
mypkg/templates =
*.xml
See also: Data Files Support
GitHub supports asciidoc readme files, but it looks like "include" is not supported.
I want to use doctoolchain which can render and export to html and pdf (and maybe into other formats). This tool works great.
I could use raw.githack.com to show the generated html file from the GitHub repository.
But I think it would be a good idea to have the result also as one (1) readme.adoc file.
How to export into one (1) asciidoc file, which I could use as it is as readme file so that github will render it and show? Best would be to use doctoolchain, when this tool will render my documentation it could also generate the one-file-asciidoc-documentation.
I think internally asciidoctor collects and merge all these "include" files. So maybe this file is already available in any place? The doctoolchain build folder contains only the target files.
You are right there is a long dicussion why includeis not supported by github.
You can achieve your goal with doctoolChain and pandoc(https://pandoc.org/). Following steps are required:
configure your docDir/Config.groovy
inputFiles should have docbook defined
inputFiles = [[file: 'yourfile', formats['docbook']]]
run the doctoolchain task generateDocbook - it creates ???.xml file somewhere in docDir/build
generate from the generated docbook again an asciidoctor file - `pandoc <FILENAME_OF_GENERATED_DOCBOOK.XML> -f docbook -t asciidoctor -o <FILENAME_OF_ASCIIDOCTOR_WHICH_HAS_EVERYTHING>
make sure it runs automatically and you commit it regulary
now you are ready
This script can be used to resolve includes and to generate one (1) output file:
https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb
some information about the script and possible next steps you can read here:
AsciiDoc Backend (AsciiDoc 2 AsciiDoc) for preprocessing
to use it, ruby and asciidoc must be installed:
asciidoctor.org/#installation
I have written the documentation for a medium sized C++ piece of software using Doxygen together with Markdown. I am quite happy with it, as after changing the xml layer I ended up with something like that:
http://docs.mitk.org/nightly/index.html
I would like to bring this documentation online, ideally using something like ReadtheDocs, where the documentation would be automatically built after a "git commit", and hosted to be browsed.
ReadtheDocs looks like the ideal site but uses Sphinx and reStructuredText as defaults. Doxygen can be used too, but AFAIK only through Breathe. Going through that route essentially means that I would need to re-structure all the documentation if I don't want to dump all the API documentation into a single page (http://librelist.com/browser//breathe/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f).
Paradoxically, Doxygen is installed in the read-the-docs server, but after struggling I could not find a workaround to skip its Sphinx or Mkdocs.
I've tried the following solution to use Doxygen on Read The Docs and it seems to work:
set up empty sphinx project (refer to official sphinx doc),
in sphinx conf.py add command to build doxygen documentation,
use conf.py html_extra_path config directive to overwrite generated doxygen documentation over generated sphinx documentation.
I've tested this with following source tree:
.../doc/Doxyfile
/build/html
/sphinx/conf.py
/sphinx/index.rst
/sphinx/...
Some explanation:
in my setup doxygen generates its documentation in "doc/build/html",
ReadTheDocs runs its commands in directory where it finds conf.py file.
What to do:
add following lines in conf.py to generate doxygen docs:
import subprocess
subprocess.call('cd .. ; doxygen', shell=True)
update conf.py html_extra_path directive to:
html_extra_path = ['../build/html']
In this configuration ReadTheDocs should properly generate and store Doxygen html documentation.
todo:
other documentation formats, for example: pdf.
This answer builds upon the great one already given by "kzeslaf". So follow the steps described by him first, before you continue here.
While his answer works as intended, I had the problem that ReadTheDocs (RTD) uses a rather old version of Doxygen (1.8.13 at the time of writing). This caused several issues for me like the one reported here. Additionally, if you set up Doxygen to treat warnings as errors, you might need to override this option on RTD due to version-related warnings.
I found a simple solution to upgrade the Doxygen version on RTD using conda.
Create an environment.yml file somewhere in your project (probably in the documentation directory). The content is as follows:
name: RTD
channels:
- conda-forge
- defaults
dependencies:
- python=3.8
- doxygen=<VERSION>
Replace <VERSION> with any version number that you like to use and that is available on conda-forge. Use conda search doxygen -c conda-forge to get a list of all available versions or simply check this site. You can also remove =<VERSION> and conda should install the latest one automatically.
Now you need to create an RTD config file if you haven't done this already. Add the following lines:
conda:
environment: <DIRECTORY>/environment.yml
Replace <DIRECTORY> with the actual location of the environment.yml file (relative to your project root, for example: docs/environment.yml). Now, if you followed all the steps in the answer of "kzelaf" and the ones I mentioned, RTD should successfully build your Doxygen documentation with the version you selected. You can check it in the lower right corner of the created pages. Alternatively, add subprocess.run(["doxygen", "-v"]) to your conf.py and check the RTD build logs.
I'd like to know whether there is a way to change the default tool to generate message sequence charts (msc) of Doxygen. Actual default tool for Doxygen is the mscgen (http://www.mcternan.me.uk/mscgen/) and it's a good tool, but I'd like to use msc-gen (https://sites.google.com/site/mscgen2393/) that seems to be a more complete tool.
I've already tried to create a link at "MSCGEN_PATH = /usr/bin/" to the msc-gen (like ln -s /usr/bin/msc-gen ./mscgen) but command line of tools are different. There is a specific way to configure Doxygen to "learn" this new tool command line?
For the current msc-gen version (v4.0.0), your solution should work.
I just tried setting the MSCGEN_PATH to the msc-gen installation directory and it worked for me. msc-gen already brings a copy of its main executable with the name mscgen.exe to be called by doxygen.
This solution is also described in the second paragraph of:
http://msc-generator.sourceforge.net/help/4.0/
You may also like to have a look at Plant UML and its doxygen integration:
http://plantuml.com/index.html
http://plantuml.com/doxygen.html
I'm using CMake 2.8.2 version. The project is using lots of external files and custom libraries (unavailable through find_package) and there is a long cascade of elements like the one below:
find_path(XXX_INCLUDE_DIR XXX.h /XXX/include)
if (XXX_INCLUDE_DIR)
message(STATUS "Includes (XXX) found in ${XXX_INCLUDE_DIR}")
else()
message(FATAL_ERROR "Includes (XXX) not found")
endif()
There is over 20 things like this in the script - it doesn't look good. According to the documentation, unfortunately, neither find_path nor find_library have a REQUIRED option which would do the job here (just like it does with find_package - if not found, the script stops). Do you have an idea how can I shorten the CMake script code? Something like
find_path(XXX_INCLUDE_DIR XXX.h /XXX/include REQUIED)
or something similar would be great.
Put them in your custom FindXXX.cmake modules. Read the docs and look at FindPNG.cmake for an example. Put them into <project>/cmake/FindXXX.cmake (or similar), and then add the directory containing these files to the CMAKE_MODULE_PATH and use find_package(), e.g.
list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
find_package(XXX REQUIRED)
You probably want to use either a macro or a function.