Generate docs for aspects too when doing setup.py docs

[Makman2]

What https://github.com/coala/aspect-docs does right now should be embedded as a build-step in our setup.py docs command and put into the API docs.

Then we can archive/move to GitLab/delete that repo.

[gitmate-bot]

GitMate.io thinks possibly related issues are #3785 (Docs: Let setup.py docs generate them from the current repo, not installation), #1493 (setup.py: Make docs), #2536 (No generated API docs for Linter), #4501 (Fix DataClump aspect docs ), and #3869 (aspects/taste.py: Typo Error).

[lalitmee]

@Makman2 I would like to do this. but I need some help in understanding somethings. 😇
Actually I was having a look at setup.py just now. I think you are talkin about this code:

class BuildDocsCommand(setuptools.command.build_py.build_py):
    apidoc_command = (
        'sphinx-apidoc', '-f', '-o', 'docs', '--no-toc', 'coalib'
    )
    doc_command = ('make', '-C', 'docs', 'html', 'SPHINXOPTS=-W')

    def run(self):
        errOne = call(self.apidoc_command)
        errTwo = call(self.doc_command)
        sys.exit(errOne or errTwo)

[Makman2]

Yes that looks like the right location 👍

[jayvdb]

The setup.py docs as part of this issue is not important.

The generator is at https://github.com/coala/aspect-docs/blob/master/generate

If we are importing it, the first step is importing the history to this repo, otherwise it is a copyright violation. The alternative is also easy: the authors can re-import it here.

Then that generator needs to be called before sphinx and be integrated into the docs/ so that sphinx picks up the generated files.

[lalitmee]

Yeah, actually this was the problem what I was facing in doing this issue. I was not getting that how can we import that whole repo. Since there is a file generate which builds the docs after ./generate, I was thinking that we can import that generate file here in coala. But I was not sure. I also asked for help on the gitter but no luck. 🤔

[jayvdb]

Also worth investigating is creating a sphinx plugin which does a similar job to the generate script.

[jayvdb]

Also worth considering, we have aspect metadata obtained via --json (#2467), and then convert that to rst.

[jayvdb]

#5426 will allow the generated docs to be viewed as part of the PR