The documentation is out of date

[opetany93]

I tried to use this package to automate some things in Bitbucket Pipelines and I wasted a whole day on it, because it didn't work at all. Only after analyzing the code I realized that the documentation doesn't match with that what is written in the code... so maybe it would be good idea to update the documentation and the given examples?

[Spacetown]

@opetany93 The code consists of several lines. Which part doesn't match the documentation? You can also create a Pr to fix the documentation.

[djanatyn]

I saw that this is still an issue in the community Discord this morning:

It looks like that documentation was removed in January: https://github.com/atlassian-api/atlassian-python-api/commit/1b4ca92d030c42ae2535aadf5798f5ea0d1739ac

However, it's still showing up on the site currently:

❯ curl -vL 'https://atlassian-python-api.readthedocs.io/_sources/index.rst.txt' 2>/dev/null  | rg 'Key/Cert Based authentication' -A 20
Key/Cert Based authentication
-----------------------------

Add a connection using key/cert based authentication:

.. code-block:: python

    from atlassian import Jira
    from atlassian import Confluence
    from atlassian import Bitbucket
    from atlassian import ServiceDesk
    from atlassian import Xray

    jira = Jira(
        url='http://localhost:8080',
        key='/path/to/key',
        cert='/path/to/cert')

    confluence = Confluence(
        url='http://localhost:8090',
        key='/path/to/key',

Some (maybe all?) of the documentation changes being made are not being pushed to the site. Unfortunately, it looks like some of the issues users are running into have already been addressed through doc changes, but the website (Read The Docs) is stale.

[djanatyn]

Actually, looking at the header of the source of https://atlassian-python-api.readthedocs.io/, the docs have not been updated since 2018:

• https://atlassian-python-api.readthedocs.io/_sources/index.rst.txt

  .. Atlassian Python API documentation master file, created by
  sphinx-quickstart on Thu Sep 13 13:43:20 2018.
  You can adapt this file completely to your liking, but it should at least
  contain the root `toctree` directive.

[Spacetown]

@djanatyn Strang, the content of https://atlassian-python-api.readthedocs.io/bitbucket.html#pipelines-management is from 2ea0484739da991853ae07a5963d4b7caed26c60

[djanatyn]

It looks like most of the documentation builds are succeeding, there just hasn't been a build in over 3 months:

• https://readthedocs.org/projects/atlassian-python-api/builds/

This is the last build for latest:

• https://readthedocs.org/projects/atlassian-python-api/builds/12681181/

It was built from https://github.com/atlassian-api/atlassian-python-api/commit/991948ba49e7bca1f299bbe89e9e879277e748f7 which does not have the documentation changes (so that explains why https://github.com/atlassian-api/atlassian-python-api/commit/1b4ca92d030c42ae2535aadf5798f5ea0d1739ac isn't on the site).

Maybe this could be addressed by adding a webhook: https://docs.readthedocs.io/en/stable/webhooks.html

[djanatyn]

Actually, looking at the header of the source of https://atlassian-python-api.readthedocs.io/, the docs have not been updated since 2018:

This isn't correct - I was confused about the docs on the site. The date I was looking at is actually hard-coded into the file and doesn't reflect the most recent build: https://raw.githubusercontent.com/atlassian-api/atlassian-python-api/master/docs/index.rst

The site was updated at least 3 months ago: https://readthedocs.org/projects/atlassian-python-api/builds/12681181/

[Spacetown]

The build fails while compiling kerberos and this dependency was moved with 2170f270e16765bd810b20b3d418e22cd1f894de from setup.py to requirements.txt. I think that in contrast to setup.py this file is also used for building the documentation.

[gonchik]

Hi! I have removed that date to reduce confusion. next step is adjust sphinx to generate automatically rst files

[gonchik]

Now it generates correctly. Just need to add some docs into wrapper