Readthedocs.org: Prend en charge les documents d'API générés automatiquement

fwiw, je serais également heureux si RTD me permettait simplement de spécifier mon propre processus de construction, de sorte qu'il ne serait pas spécifiquement compatible avec le code dur pour sphinx-apidoc . Bien que cela puisse également être difficile à autoriser de manière sécurisée.

J'essaie également d'utiliser sphinx-apidoc pour ma documentation. J'utilise un tox -e docs pour générer mes docs

+1 à ce sujet... Je suis sûr, même en le documentant dans la procédure de publication, que j'oublierai de générer les apidocs et de les valider...

Nous développons actuellement un nouveau système de construction. Et je suppose que nous pourrions intégrer cela d'une manière ou d'une autre. Cependant, ce n'est pas encore là, donc je suppose que nous n'aurons pas de solution pour cela dans les prochaines semaines, mais plus dans les mois.

+1

L'ajout de ce support serait incroyable et réduirait considérablement les frictions associées à la mise à jour de la documentation. Si sphinx-apidoc était pris en charge dans readthedocs, un développeur n'aurait même pas besoin de la chaîne d'outils sphinx installée localement s'il ne le voulait pas ; leur seule responsabilité serait de tenir à jour les docstrings.

+1

:+1:

+1

+1

Pour votre information, vous pouvez contourner ce problème en ajoutant quelque chose comme ce qui suit au fichier conf.py de votre projet :

def run_apidoc(_):
    modules = ['a_list_of',
               'python_module_directories',
               'in_your_project']
    for module in modules:
        cur_dir = os.path.abspath(os.path.dirname(__file__))
        output_path = os.path.join(cur_dir, module, 'doc')
        cmd_path = 'sphinx-apidoc'
        if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv
            # If we are, assemble the path manually
            cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'sphinx-apidoc'))
        subprocess.check_call([cmd_path, '-e', '-o', output_path, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

Cela exécutera sphinx-apidoc pendant l'événement principal sphinx initié par le constructeur. Cela devrait fonctionner sur readthedocs ainsi que localement, vous permettant de générer automatiquement vos documents api sans avoir à stocker la sortie dans votre référentiel git. Vous pouvez même croiser votre documentation manuelle avec ces références d'API.

Une autre solution qui n'implique pas d'appeler directement un sous-processus consiste à utiliser ce qui suit dans conf.py :

from sphinx.apidoc import main
main(['-e', '-o', ...])

au lieu de

subprocess.check_call([cmd_path, '-e', '-o', output_path, module, '--force'])

Cela a résolu l'un des problèmes que j'avais avec les noms de chemin longs qui sont restreints sur readthedocs.

@alyjak @Maxyme Merci. Et cela fonctionne pour moi.

def run_apidoc(_):
    from sphinx.apidoc import main
    import os
    import sys
    sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
    cur_dir = os.path.abspath(os.path.dirname(__file__))
    module = '.'
    output_path = os.path.join(cur_dir, 'source')
    # main(['-e', '-o', output_path, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

@BowenFu

Merci! Cependant, pour que votre code fonctionne, vous devez décommenter la ligne main . Et surtout, j'ai trouvé cela incompatible avec la structure de répertoires que je vois couramment, où les fichiers source .rst sont tous placés dans le répertoire de documentation (où se trouve également config.py ). Ce qui a fonctionné pour moi était:

def run_apidoc(_):
    from sphinx.apidoc import main
    import os
    import sys
    sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
    cur_dir = os.path.abspath(os.path.dirname(__file__))
    module = os.path.join(cur_dir,"..","labbookdb")
    main(['-e', '-o', cur_dir, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

Deux commentaires sur le code de @TheChymera , qui fonctionne généralement très bien et que j'utilise maintenant :

• Vous devrez remplacer labbookdb par le nom de votre module
• Étant donné que l'analyse des options commence par le deuxième élément de la liste, -e n'est pas honoré ; si vous voulez une page distincte par module, vous devrez ajouter None à la liste transmise à main .

Sinon, une bonne solution au problème d'automatisation des mises à jour de la documentation de l'API. Merci!!

Je ne sais pas s'il s'agit d'une fonctionnalité que nous allons implémenter directement dans RTD. Avoir la solution ci-dessus dans nos documents serait cependant un grand pas en avant ! Nous avons un contenu similaire sous docs/guides .

Si nous implémentions cela n'importe où, je pense que nous pourrions l'implémenter dans notre configuration YAML.

Depuis la dernière version, le comportement est le même que celui de la construction de la documentation locale, comme prévu. J'ai donc supprimé la solution de contournement faite en mars.

Merci pour le correctif.

@Guts , cela signifie que vous ajoutez simplement l'extension et que cela fonctionne comme prévu ? Pouvons-nous alors clore ce sujet ?

Aussi, peut-être que vous voulez utiliser https://github.com/rtfd/sphinx-autoapi

@Guts , cela signifie que vous ajoutez simplement l'extension et que cela fonctionne comme prévu ? Pouvons-nous alors clore ce sujet ?

Oui. J'ai supprimé la solution de contournement et cela fonctionne. Je pense donc que cela fonctionne comme prévu. Pour clore le sujet, peut-être devrions-nous attendre les commentaires de l'auteur ? cc @radix

Aussi, peut-être que vous voulez utiliser https://github.com/rtfd/sphinx-autoapi

Je n'ai pas vraiment testé https://github.com/rtfd/sphinx-autoapi car il dit Python 2 uniquement ( Python (2 only -- Epydoc doesn't support Python 3) ) et je n'ai pas beaucoup de temps pour essayer et comprendre une autre extension Sphinx (Je ne suis pas un expert en doc, donc cela me demanderait de vraiment plonger).

Merci pour votre retour, je fermerai ceci dans quelques jours si l'auteur original ne répond pas ou si quelqu'un d'autre a ce problème :)

oui, allez-y et fermez-le si vous avez une résolution, je n'aurai pas l'occasion de le vérifier bientôt. Merci beaucoup!

Ok, je ferme, s'il vous plaît laissez-nous savoir si vous avez à nouveau le problème ou si la solution fonctionne pour vous aussi

J'ai utilisé le correctif @TheChymera avec beaucoup de succès jusqu'à présent, mais je dois le commenter lorsque je veux créer la documentation localement.

La mise à jour de @Guts signifie-t-elle que je peux supprimer ce correctif, ajouter extensions = ['autoapi.extension'] dans mon conf.py et qu'il fonctionnera à la fois localement et sur RTD ?

Edit: je ne m'en étais pas rendu compte à l'époque, mais autoapi et sphinx-apidoc sont des bibliothèques trop différentes avec des méthodes d'analyse différentes. La sortie peut être légèrement différente.

La mise à jour de @Guts signifie-t-elle que je peux abandonner ce correctif, ajouter des extensions = ['autoapi.extension'] dans mon conf.py, et qu'il fonctionnera à la fois localement et sur RTD ?

Je pense que oui, si vous avez besoin d'exécuter du code de manière conditionnelle, vous pouvez voir https://docs.readthedocs.io/en/latest/faq.html#how -do-i-change-behavior-for-read-the-docs

La mise à jour de @Guts signifie-t-elle que je peux abandonner ce correctif, ajouter des extensions = ['autoapi.extension'] dans mon conf.py, et qu'il fonctionnera à la fois localement et sur RTD ?

C'est ce que ça signifie. Au moins, c'est ce que j'ai fait : une solution de contournement pour gérer les environnements de construction locaux/RTD, puis la supprimer avec la mise à jour RTD.

Sphinx 1.6 à 1.7 a cassé certaines choses sur lesquelles la solution de contournement susmentionnée s'appuyait. Une version compatible Sphinx 1.6 et 1.7+ est incluse ci-dessous.

def run_apidoc(_):
    ignore_paths = [
        ...
    ]

    argv = [
        "-f",
        "-T",
        "-e",
        "-M",
        "-o", ".",
        ".."
    ] + ignore_paths

    try:
        # Sphinx 1.7+
        from sphinx.ext import apidoc
        apidoc.main(argv)
    except ImportError:
        # Sphinx 1.6 (and earlier)
        from sphinx import apidoc
        argv.insert(0, apidoc.__file__)
        apidoc.main(argv)


def setup(app):
    app.connect('builder-inited', run_apidoc)

Il semble qu'il y ait du travail en cours en amont pour ajouter l'auto-génération de documents API à Sphinx.

xréf : https://github.com/sphinx-doc/sphinx/pull/4101

Il semble qu'il y ait du travail en cours en amont pour ajouter l'auto-génération de documents API à Sphinx.

xréf : sphinx-doc/sphinx#4101

Ceci est également pris en charge hors de l'arborescence à l'aide de l'extension sphinxcontrib.apidoc . Ceci est largement utilisé dans la communauté OpenStack et fonctionne assez bien pour nos besoins.

Avec Sphinx 3.1.1 j'avais besoin d'importer
from sphinx.ext.apidoc import main
au lieu de
from sphinx.apidoc import main