Skip to content

Commit db3483b

Browse files
rusherrusher
committed
[misc] doc generation correction
1 parent cf7d09c commit db3483b

19 files changed

+785
-931
lines changed

‎.github/workflows/release.yml

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
name: Generate and Update API Docs
22

33
on:
4-
workflow_dispatch: # Allow manual triggering
4+
workflow_dispatch:
5+
branches: [1.1]
56
release:
6-
types: [published] # Runs when release is published
7+
types: [published]
8+
branches: [1.1]
79

810
jobs:
911
update-docs:
@@ -102,10 +104,24 @@ jobs:
102104
run: |
103105
# Remove existing documentation in target subdirectory
104106
105-
mkdir -p mariadb-docs/connectors/mariadb-connector-python/api/
106-
rm -rf mariadb-docs/connectors/mariadb-connector-python/api/*
107+
rm -f mariadb-docs/connectors/mariadb-connector-python/api.md
108+
rm -f mariadb-docs/connectors/mariadb-connector-python/bugs.md
109+
rm -f mariadb-docs/connectors/mariadb-connector-python/connection.md
110+
rm -f mariadb-docs/connectors/mariadb-connector-python/constants.md
111+
rm -f mariadb-docs/connectors/mariadb-connector-python/cursor.md
112+
rm -f mariadb-docs/connectors/mariadb-connector-python/faq.md
113+
rm -f mariadb-docs/connectors/mariadb-connector-python/install.md
114+
rm -f mariadb-docs/connectors/mariadb-connector-python/license.md
115+
rm -f mariadb-docs/connectors/mariadb-connector-python/module.md
116+
rm -f mariadb-docs/connectors/mariadb-connector-python/pool.md
117+
rm -f mariadb-docs/connectors/mariadb-connector-python/pooling.md
118+
rm -f mariadb-docs/connectors/mariadb-connector-python/index.md
119+
rm -f mariadb-docs/connectors/mariadb-connector-python/usage.md
120+
rm -f mariadb-docs/connectors/mariadb-connector-python/release.md
121+
107122
# Copy new documentation
108-
cp -r docs/_build/markdown/* mariadb-docs/connectors/mariadb-connector-python/api/
123+
cp -r docs/_build/markdown/* mariadb-docs/connectors/mariadb-connector-python/
124+
mv -f mariadb-docs/connectors/mariadb-connector-python/index.md mariadb-docs/connectors/mariadb-connector-python/README.md
109125
110126
# Optional: Add any additional processing here
111127
# e.g., update index files, fix relative links, etc.
@@ -116,7 +132,7 @@ jobs:
116132
git config user.name "github-actions[bot]"
117133
git config user.email "github-actions[bot]@users.noreply.github.com"
118134
git checkout -b auto-docs-update-${{ github.run_number }}
119-
git add connectors/mariadb-connector-python/api/
135+
git add connectors/mariadb-connector-python/
120136
git commit -m "Update API documentation from ${{ github.repository }}"
121137
git push https://x-access-token:${{ secrets.SPHINX_TOKEN }}@github.com/rusher/mariadb-docs.git auto-docs-update-${{ github.run_number }}
122138

‎CHANGELOG.md

Lines changed: 309 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/source/api.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ API Reference
1414
pool
1515
constants
1616

17+
{% @marketo/form formId=\"4316\" %}

‎docs/source/bugs.rst

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,19 @@ How to report a bug?
99

1010
Search first
1111
^^^^^^^^^^^^
12-
Always search the bug database first. Especially if you are using an older version of MariaDB Connector/Python it could
13-
be reported already by someone else or it was already fixed in a more recent version.
12+
Always search the bug database first. Especially if you are using an older version of MariaDB Connector/Python it could be reported already by someone else or it was already fixed in a more recent version.
1413

1514
What?
1615
^^^^^
17-
We need to know what you did, what happened and what you wanted to happen. A report stating that method xyz() hangs, will
18-
not allow us to provide you with an advice or fix, since we just don't know what the method is doing.
19-
Beside versions a good bug report contains a short script which reproduces the problem. Sometimes it is also necessary to
16+
We need to know what you did, what happened and what you wanted to happen. A report stating that method xyz() hangs, will not allow us to provide you with an advice or fix, since we just don't know what the method is doing.
17+
Beside versions, a good bug report contains a short script which reproduces the problem. Sometimes it is also necessary to
2018
provide the definition (and data) of used tables.
2119

2220
Versions of components
2321
^^^^^^^^^^^^^^^^^^^^^^
24-
MariaDB Connector/Python interacts with two other components: The database server and MariaDB Connector/C. Latter one is responsible for client/server communication. An error does not necessarily have to exist in Connector / Python; it can also be an error in the database server or in Connector/C. In this case we will reclassify the bug (MDEV or CONC).
22+
MariaDB Connector/Python interacts with two other components: The database server and MariaDB Connector/C. The latter one is responsible for client/server communication.
23+
An error does not necessarily have to exist in Connector / Python; it can also be an error in the database server or in Connector/C.
24+
In this case, we will reclassify the bug (MDEV or CONC).
2525

2626
Avoid screenshots!
2727
^^^^^^^^^^^^^^^^^^
@@ -30,11 +30,9 @@ read on mobile devices. Typing program code from a screenshot is also an unneces
3030

3131
Keep it simple!
3232
^^^^^^^^^^^^^^^
33-
Scripts which are longer than 10 lines often contain code which is not relevant to the problem and increases
34-
the time to figure out the real problem. So try to keep it simple and focus on the real problem.
33+
Scripts which are longer than 10 lines often contain code which is not relevant to the problem and increases the time to figure out the real problem. So try to keep it simple and focus on the real problem.
3534

36-
The sane applies for database related components like tables, views and stored procedures. Avoid table definitions with
37-
hundred of columns if the problem can be reproduced with only 4 columns,
35+
The sane applies for database related components like tables, views, and stored procedures. Avoid table definitions with hundreds of columns if the problem can be reproduced with only 4 columns.
3836

3937
Only report one problem in one bug report
4038
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -46,3 +44,5 @@ If your application crashes, please also provide if possible a backtrace and out
4644

4745
Report bugs in English only!
4846
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
47+
48+
{% @marketo/form formId=\"4316\" %}

‎docs/source/connection.rst

Lines changed: 37 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -10,36 +10,37 @@ The connection class
1010
Connection constructors
1111
-----------------------
1212

13-
.. automethod:: mariadb.connections.Connection.cursor
14-
15-
.. versionadded:: 1.0.1
1613
.. automethod:: mariadb.connections.Connection.xid
1714

15+
*Since version 1.0.1.*
16+
1817
------------------
1918
Connection methods
2019
------------------
2120

22-
.. versionadded:: 1.1.0
2321
.. automethod:: mariadb.connections.Connection.begin
2422

23+
*Since version 1.1.0.*
24+
2525
.. automethod:: mariadb.connections.Connection.commit
2626

27-
.. automethod:: mariadb.connections.Connection.change_user(user, password, database)
27+
.. automethod:: mariadb.connections.Connection.change_user
2828

2929
.. automethod:: mariadb.connections.Connection.close
3030

3131
.. automethod:: mariadb.connections.Connection.cursor
3232

33-
.. versionadded:: 1.1.2
3433
.. automethod:: mariadb.connections.Connection.dump_debug_info
3534

35+
*Since version 1.1.2.*
36+
3637
.. automethod:: mariadb.connections.Connection.get_server_version
3738

38-
.. versionadded:: 1.0.5
3939
.. automethod:: mariadb.connections.Connection.escape_string
4040

41-
.. testcode::
41+
*Since version 1.0.5.*
4242

43+
.. testcode::
4344
import mariadb
4445

4546
# connection parameters
@@ -49,36 +50,34 @@ Connection methods
4950
"host" : "localhost"
5051
}
5152

52-
# Establish a connection
53-
connection= mariadb.connect(**conn_params)
54-
55-
string= 'This string contains the following special characters: \,"'
56-
print(connection.escape_string(string))
53+
with mariadb.connect(**conn_params) as connection:
54+
string = 'This string contains the following special characters: \\,"'
55+
print(connection.escape_string(string))
5756
58-
*Output*:
57+
**Output:**
5958

6059
.. testoutput::
6160

62-
This string contains the following special characters: \\,\"
63-
61+
This string contains the following special characters: \\,\"
6462

6563
.. automethod:: mariadb.connections.Connection.kill
6664

67-
.. note::
68-
A thread_id from other connections can be determined by executing the SQL statement ``SHOW PROCESSLIST``
69-
The thread_id of the current connection the current connection is stored in :data:`connection_id` attribute.
65+
.. note::
66+
A thread_id from other connections can be determined by executing the SQL statement ``SHOW PROCESSLIST``.
67+
The thread_id of the current connection is stored in the :data:`connection_id` attribute.
7068

71-
.. automethod:: mariadb.connections.Connection.ping()
69+
.. automethod:: mariadb.connections.Connection.ping
7270

7371
.. automethod:: mariadb.connections.Connection.reconnect
7472

7573
.. automethod:: mariadb.connections.Connection.reset
7674

77-
.. automethod:: mariadb.connections.Connection.rollback()
75+
.. automethod:: mariadb.connections.Connection.rollback
7876

79-
.. versionadded:: 1.1.0
8077
.. automethod:: mariadb.connections.Connection.select_db
8178

79+
*Since version 1.1.0.*
80+
8281
.. automethod:: mariadb.connections.Connection.show_warnings
8382

8483
.. automethod:: mariadb.connections.Connection.tpc_begin
@@ -101,47 +100,56 @@ Connection attributes
101100

102101
.. autoattribute:: mariadb.connections.Connection.character_set
103102

104-
.. versionadded:: 1.1.0:
105103
.. autoattribute:: mariadb.connections.Connection.client_capabilities
106104

105+
*Since version 1.1.0.*
106+
107107
.. autoattribute:: mariadb.connections.Connection.collation
108108

109109
.. autoattribute:: mariadb.connections.Connection.connection_id
110110

111111
.. autoattribute:: mariadb.connections.Connection.database
112112

113-
.. versionadded:: 1.1.0
114113
.. autoattribute:: mariadb.connections.Connection.open
115114

116-
.. versionadded:: 1.1.0
115+
*Since version 1.1.0.*
116+
117117
.. autoattribute:: mariadb.connections.Connection.server_capabilities
118118

119-
.. versionadded:: 1.1.0
119+
*Since version 1.1.0.*
120+
120121
.. autoattribute:: mariadb.connections.Connection.extended_server_capabilities
121122

123+
*Since version 1.1.0.*
124+
122125
.. autoattribute:: mariadb.connections.Connection.server_info
123126

124127
.. autoattribute:: mariadb.connections.Connection.server_name
125128

126129
.. autoattribute:: mariadb.connections.Connection.server_port
127130

128-
.. versionadded:: 1.1.0
129131
.. autoattribute:: mariadb.connections.Connection.server_status
130132

133+
*Since version 1.1.0.*
134+
131135
.. autoattribute:: mariadb.connections.Connection.server_version
132136

133137
.. autoattribute:: mariadb.connections.Connection.server_version_info
134138

135-
.. versionadded:: 1.0.5
136139
.. autoattribute:: mariadb.connections.Connection.tls_cipher
137140

141+
*Since version 1.0.5.*
142+
138143
.. autoattribute:: mariadb.connections.Connection.tls_version
139144

140-
.. versionadded:: 1.1.11
141145
.. autoattribute:: mariadb.connections.Connection.tls_peer_cert_info
142146

147+
*Since version 1.1.11.*
148+
143149
.. autoattribute:: mariadb.connections.Connection.unix_socket
144150

145151
.. autoattribute:: mariadb.connections.Connection.user
146152

147153
.. autoattribute:: mariadb.connections.Connection.warnings
154+
155+
{% @marketo/form formId=\"4316\" %}

0 commit comments

Comments
 (0)